Documentation/docs/volume/mounts

#Volume Mounts

After mounting a Volume to a Sandbox, you can access Volume data within the Sandbox just like a local filesystem.

Mount Flow#

Mount a Volume#

When mounting, you need to specify:

  • volume_id: The Volume ID to mount
  • mount_point: The mount path inside the Sandbox
  • volume_config (optional): Performance configuration override at mount time

Mount point requirements from the current infra implementation:

  • Must be an absolute path (for example /mnt/data)
  • Cannot be root path (/)
  • If the directory does not exist, it is created automatically
go
volume, err := client.CreateVolume(ctx, apispec.CreateSandboxVolumeRequest{
  AccessMode: apispec.NewOptVolumeAccessMode(apispec.VolumeAccessModeRWX),
  CacheSize:  apispec.NewOptString("1G"),
  BufferSize: apispec.NewOptString("128M"),
})
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Volume ID: %s\n", volume.ID)

// Mount Volume to Sandbox
mountResp, err := sandbox.Mount(ctx, volume.ID, "/mnt/data", nil)
if err != nil {
  panic(err)
}
fmt.Printf("Volume mounted at %s\n", mountResp.MountPoint)
fmt.Printf("Mount session ID: %s\n", mountResp.MountSessionID)

// Operate files inside Sandbox
_, err = sandbox.WriteFile(ctx, "/mnt/data/hello.txt", []byte("Hello, Volume!"))
if err != nil {
  panic(err)
}
content, err := sandbox.ReadFile(ctx, "/mnt/data/hello.txt")
if err != nil {
  panic(err)
}
fmt.Printf("File content: %s\n", string(content))

Bootstrap Mounts During Claim#

If you already know which existing Volumes a sandbox should start with, you can include bootstrap mounts directly in the sandbox claim request.

This is useful when a claimed sandbox should immediately open a pre-existing project workspace or dataset.

The claim request accepts:

  • mounts[]: existing volumes to mount into the sandbox
  • wait_for_mounts: optional best-effort wait for the requested mounts to reach a terminal state
  • mount_wait_timeout_ms: optional wait budget for wait_for_mounts

Cold-start note:

  • By default, claim-time mounts are asynchronous bootstrap work.
  • When wait_for_mounts is omitted or false, the claim API can return before mounts finish.
  • Use /api/v1/sandboxes/{'{'}id{'}'}/sandboxvolumes/status or the SDK claim response to inspect mount state (pending, mounting, mounted, failed).

Example request:

json
{
    "template": "default",
    "mounts": [
        {
            "sandboxvolume_id": "vol_123",
            "mount_point": "/workspace/data"
        }
    ],
    "wait_for_mounts": true,
    "mount_wait_timeout_ms": 30000
}

The claim response now includes bootstrap_mounts, so callers can tell whether requested mounts are still pending, already mounted, or failed with an error.

go
volume, err := client.CreateVolume(ctx, apispec.CreateSandboxVolumeRequest{})
if err != nil {
  log.Fatal(err)
}

sandbox, err := client.ClaimSandbox(
  ctx,
  "default",
  sandbox0.WithSandboxBootstrapMount(volume.ID, "/workspace/data", nil),
  sandbox0.WithSandboxBootstrapMountWait(30*time.Second),
)
if err != nil {
  log.Fatal(err)
}

for _, mount := range sandbox.BootstrapMounts {
  fmt.Printf("Volume: %s, Path: %s, State: %s\n", mount.SandboxvolumeID, mount.MountPoint, mount.State)
}

Override Performance Config at Mount Time#

You can specify different performance parameters than the Volume's default:

go
//_, err = sandbox.Mount(ctx, volume.ID, "/mnt/data", &apispec.VolumeConfig{
//	CacheSize:  apispec.NewOptString("1G"),
//	BufferSize: apispec.NewOptString("256M"),
//	Prefetch:   apispec.NewOptInt32(4),
//	Writeback:  apispec.NewOptBool(false),
//})
//if err != nil {
//	panic(err)
//}

Query Mount Status#

go
mounts, err := sandbox.MountStatus(ctx)
if err != nil {
  panic(err)
}
for _, mount := range mounts {
  fmt.Printf("Volume: %s, Path: %s, Session: %s, State: %s\n", mount.SandboxvolumeID, mount.MountPoint, mount.MountSessionID, mount.State)
}

Unmount a Volume#

When unmounting, provide the mount_session_id returned from the mount operation:

go
_, err = sandbox.Unmount(ctx, volume.ID, mountResp.MountSessionID)
if err != nil {
  panic(err)
}

Share Volume Across Sandboxes#

Volumes with RWX access mode can be mounted to multiple Sandboxes simultaneously:

go
// Create RWX Volume
volume, err = client.CreateVolume(ctx, apispec.CreateSandboxVolumeRequest{
  AccessMode: apispec.NewOptVolumeAccessMode(apispec.VolumeAccessModeRWX),
})
if err != nil {
  panic(err)
}

// Create two Sandboxes
sandbox1, err := client.ClaimSandbox(ctx, "default")
if err != nil {
  panic(err)
}
sandbox2, err := client.ClaimSandbox(ctx, "default")
if err != nil {
  panic(err)
}

// Mount same Volume to both Sandboxes
mount1, err := sandbox1.Mount(ctx, volume.ID, "/mnt/shared", nil)
if err != nil {
  panic(err)
}
mount2, err := sandbox2.Mount(ctx, volume.ID, "/mnt/shared", nil)
if err != nil {
  panic(err)
}

// Sandbox1 writes file
_, err = sandbox1.WriteFile(ctx, "/mnt/shared/message.txt", []byte("Hello from Sandbox1"))
if err != nil {
  panic(err)
}

// Sandbox2 can read it
content, err = sandbox2.ReadFile(ctx, "/mnt/shared/message.txt")
if err != nil {
  panic(err)
}
fmt.Printf("Sandbox2 read: %s\n", string(content))
// Output: Sandbox2 read: Hello from Sandbox1

// Cleanup mounts
_, err = sandbox1.Unmount(ctx, volume.ID, mount1.MountSessionID)
if err != nil {
  panic(err)
}
_, err = sandbox2.Unmount(ctx, volume.ID, mount2.MountSessionID)
if err != nil {
  panic(err)
}
ℹ

With RWX mode, multiple Sandboxes can read and write to the same Volume simultaneously. Handle concurrent write conflicts appropriately.

ℹ

Access mode controls how the Volume can be shared across Sandboxes:

  • RWO: Read-write mount for a single Sandbox (or multiple Sandboxes strictly scheduled together)
  • ROX: Read-only mounts across any number of Sandboxes
  • RWX: Read-write mounts across any number of Sandboxes

Troubleshooting#

Mount Fails#

ℹ

If mount fails, check:

  1. Volume exists and is not deleted
  2. Sandbox is in running state
  3. Mount path is absolute and not /
  4. Mount path is not already in use by another volume in the same sandbox
  5. Access mode matches your usage pattern (e.g., trying to read-write mount an ROX volume)

409 Conflict When Deleting Volume#

ℹ

Cannot delete a Volume with active mounts. Unmount all mounts first before deleting.

Next Steps#

Volume HTTP

Operate on volume files directly by volume ID without mounting first

Snapshots

Create and restore volume snapshots

Sandbox Files

Read and write files in sandboxes

Volume Overview

Volume lifecycle, access modes, and configuration