#Volume Mounts

Volumes are mounted through template-declared mount points and bound when a Sandbox is claimed.

Dynamic mount and unmount APIs are no longer part of the Sandbox API. Define the allowed mount paths in the template, then provide the Volume IDs for those paths in the claim request.

Mount Flow#

Define Mount Points#

Template mount paths are fixed before the Sandbox starts.

yaml
apiVersion: sandbox0.ai/v1alpha1
kind: SandboxTemplate
metadata:
    name: default
spec:
    volumeMounts:
        - name: workspace
          mountPath: /workspace
          readOnly: false

The operator-managed default builtin template already declares the writable /workspace mount point. Custom templates must declare each mount point explicitly.

Mount path requirements:

name must be unique within the template.
mountPath must be an absolute, clean path.
/ is not allowed.
Paths under /var/lib/sandbox0/procd are reserved for Sandbox0 internals.

Claim With a Volume#

The claim request binds existing Volumes to template-declared paths.

json
{
    "template": "default",
    "mounts": [
        {
            "sandboxvolume_id": "vol_123",
            "mount_point": "/workspace"
        }
    ]
}

mount_point must match a path declared in spec.volumeMounts. A claim may bind any subset of the declared mount paths.

Only mounts present in the claim request are treated as bound Sandbox Volume paths for that Sandbox. Bound Sandbox Volume paths are excluded from rootfs pause, snapshot, restore, and fork checkpoints because their contents are owned by the Sandbox Volume. Declared paths omitted from the claim are created as writable rootfs directories, so their contents are captured by rootfs pause, snapshot, restore, and fork checkpoints.

Access Modes#

RWO is the high-performance read-write mount mode. Sandbox0 binds the volume to a node-local ctld portal and uses a local write-ahead log before materializing data to object storage.

ROX can be mounted only on template paths marked readOnly: true.

RWX is not accepted for Sandbox mounts in this node-local implementation. Use direct file APIs for control-plane file operations, or use separate RWO volumes for write-heavy Sandbox workloads.

S3 Backend Mounts#

Volumes created with backend: "s3" are mounted through the same template-declared volume portal. The mounted path exposes the configured S3-compatible prefix as a filesystem: keys use / as directory separators, common prefixes appear as directories, and files created inside the Sandbox are uploaded as S3 objects when the file handle is closed or flushed.

The S3 backend supports RWO and ROX mounts. Writable opens replace the target object and must write sequentially; random in-place overwrites are not supported. It does not support RWX, snapshots, restore, forks, renames, hard links, symlinks, xattrs, file locks, or fallocate. Use it when the desired source of truth is an existing S3/OSS/R2 prefix rather than a Sandbox0-managed s0fs volume.

Correctness Guarantees#

Mounted RWO volumes use one active writable owner at a time.

the mounted sandbox path is the authoritative writer
direct volume file API requests are routed to that mounted owner while the mount is active
Sandbox0 avoids opening a second writable direct mount for the same mounted RWO volume

This is what keeps file changes visible both from inside the sandbox and through the volume file API.

Operator-managed deployments keep one active and one synchronized standby ctld process on each sandbox node. The standby holds a second channel for every kernel FUSE connection and the backend recovery state needed to take over without unpublishing the portal. The elected primary also owns kubelet CSI registration, which is recreated by the promoted standby so new mounts resume after a retry. This protects existing mounts and restores new mount operations after a single ctld process or Pod failure; it does not preserve mounts across a node reboot or simultaneous loss of both processes.

File Operations#

After claim completes, use the mounted path like a normal filesystem:

bash
echo "hello" >/workspace/hello.txt
cat /workspace/hello.txt

For control-plane file operations without a Sandbox, use /api/v1/sandboxvolumes/{'{id}'}/files.