# 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

```mermaid
flowchart LR
    tmpl["SandboxTemplate<br/>volumeMounts"]
    claim["Claim request<br/>mounts"]
    ctld["ctld node portal"]
    sb["Sandbox<br/>/workspace/data"]
    vol["Volume"]

    tmpl --> claim
    claim --> ctld
    ctld --> sb
    vol --> ctld
```

## 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-data
      mountPath: /workspace/data
      readOnly: false
```

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/data"
        }
    ]
}
```

`mount_point` must match a path declared in `spec.volumeMounts`.

## 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.

## 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.

## File Operations

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

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

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

## Next Steps

<CardGroup>
  <Card title="HTTP" href="/docs/volume/http" cta="Continue">
    Use direct volume file APIs outside a running sandbox mount.
  </Card>

  <Card title="Snapshots" href="/docs/volume/snapshots" cta="Continue">
    Create and restore point-in-time volume snapshots.
  </Card>
</CardGroup>
