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

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 {
  volumeID, _ := mount.SandboxvolumeID.Get()
  mountPoint, _ := mount.MountPoint.Get()
  sessionID, _ := mount.MountSessionID.Get()
  fmt.Printf("Volume: %s, Path: %s, Session: %s\n", volumeID, mountPoint, sessionID)
}

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)
}

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:

Volume exists and is not deleted
Sandbox is in running state
Mount path is absolute and not /
Mount path is not already in use by another volume in the same sandbox
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#

Snapshots

Create and restore volume snapshots

Sandbox Files

Read and write files in sandboxes

Volume Overview

Volume lifecycle and configuration