#Volume

Volume provides persistent storage for Sandbox0. It is a storage unit independent of the Sandbox lifecycle, allowing data sharing and reuse across multiple Sandboxes.

Why Volumes?#

The default Sandbox filesystem is ephemeral—when a Sandbox is deleted, all its data is lost. Volumes solve this problem:

Data Persistence: Store data that needs long-term retention, such as databases, model files, and user uploads
Cross-Sandbox Sharing: Mount the same Volume to multiple Sandboxes for data sharing
Fast Snapshots: Create point-in-time snapshots in seconds for backup and versioning
Fast Forking: Create independent child Volumes with Copy-on-Write isolation
Quick Recovery: Restore from snapshots quickly, ideal for rollbacks and environment cloning

Volume and Sandbox Relationship#

Access Modes#

Volumes support three access modes:

Mode	Full Name	Description	Typical Use Cases
`RWO`	Read-Write Once	Single Sandbox read-write	Database storage, exclusive workspaces
`ROX`	Read-Only Cross	Multi-Sandbox read-only	Shared model files, static resource distribution
`RWX`	Read-Write Cross	Multi-Sandbox read-write	Collaborative workspaces, shared caches

ℹ

The default access mode is RWO. Specify RWX mode when creating a Volume if you need cross-Sandbox sharing.

Performance Configuration#

Volumes support the following performance tuning parameters:

Parameter	Type	Description	Example Values
`cache_size`	string	Cache size (default: `1G`)	`512M`, `1G`
`buffer_size`	string	Buffer size (default: `32M`)	`32M`, `128M`, `256M`
`prefetch`	integer	Number of blocks to prefetch (default: `0`)	`0`, `1`, `2`, `4`
`writeback`	boolean	Enable write-back cache (default: `false`)	`true`, `false`

ℹ

Enabling writeback improves write performance but may lose unwritten data in exceptional cases. Disable it for scenarios requiring strong data consistency.

Create Volume#

Create a new persistent volume with access mode and optional performance config.

POST/api/v1/sandboxvolumes

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)

Get Volume Details#

Retrieve a specific volume by ID.

GET/api/v1/sandboxvolumes/{id}

go
vol, err := client.GetVolume(ctx, volume.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Volume: %s (mode: %s)\n", vol.ID, vol.AccessMode.Value)

List Volumes#

List all volumes in the current team.

GET/api/v1/sandboxvolumes

go
volumes, err := client.ListVolume(ctx)
if err != nil {
  log.Fatal(err)
}
for _, v := range volumes {
  fmt.Printf("- %s (%s)\n", v.ID, v.AccessMode.Value)
}

Delete Volume#

Delete a volume when it is no longer needed.

DELETE/api/v1/sandboxvolumes/{id}

go
_, err = client.DeleteVolume(ctx, volume.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Volume deleted")

Persist Runtime Environment with Nix#

You can use Nix + Volume to persist and reuse your runtime environment artifacts across Sandboxes.

Can persist: dependency closures, build caches, package stores, lock files, and workspace-level toolchains
Cannot persist: live process runtime state (in-memory variables, process stacks, open sockets, PID state)

This means:

A new Sandbox can quickly reproduce the same environment from mounted Volume data
But it still starts as a new process runtime, not a paused/resumed OS process image

Next Steps#

Volume Mounts

Mount volumes to sandboxes for persistent storage

Snapshots

Create, restore, and manage volume snapshots

Volume Fork

Clone a volume with Copy-on-Write isolation

Sandbox

Sandbox lifecycle and execution management