Volumes
Persistent volumes are ext4 filesystems that survive sandbox destruction. Create one, attach it to a sandbox, destroy the sandbox — the data is still there.
The CLI surface is in Volumes reference. This page covers the rules — when you can attach, what mount paths are allowed, and which operations require the volume to be unattached.
Attaching at create time
Section titled “Attaching at create time”Volumes are mounted by lohar during sandbox boot. Specify them with --volume (repeatable):
bhatti volume create --name workspace --size 5120bhatti create --name dev --volume workspace:/workspaceThe format is <name>:<mount>[:ro]:
bhatti create --name reader --volume workspace:/data:ro:ro mounts read-only. Multiple sandboxes can mount the same volume read-only at the same time — useful for shared base data. Read-write attachment is exclusive: only one sandbox can have it as read-write at any moment.
You can attach more than one volume per sandbox by repeating --volume.
Mount path restrictions
Section titled “Mount path restrictions”Mount paths must be absolute. The guest agent rejects anything else.
You also can’t shadow system paths. Specifically, the following are blocked:
/proc /sys /dev /etc /usr /bin /sbin /lib /lib64 /run /var/runUse a fresh subtree like /workspace, /data, /srv/<app> — anywhere outside the system hierarchy.
Detached state
Section titled “Detached state”Four operations require the volume to have no sandbox attachments:
The server returns 409 Conflict if any sandbox still owns the attachment. Stopping a sandbox does not detach its volumes: it powers off the guest but retains its attachment for the next boot. To release one through the CLI, destroy that sandbox (the volume persists, its root disk does not). If you need to keep the sandbox, use a named memory snapshot to branch its whole device set rather than running a detached-only volume operation.
bhatti volume backup is the exception — it works while the volume is attached. The server holds the guest’s lifecycle, freezes the mounted filesystem on new running agents (or syncs on old agents), copies the volume locally, then thaws before compression/upload. The backup record’s consistency_mode is frozen, sync_only, or detached (no running attachment, including a stopped sandbox); historical backups can say unverified. Sync-only is not as strong as a freeze against concurrent writes. The CLI backup-list output omits this field; request the API record when you need it.
Backups
Section titled “Backups”Volume backups go to S3-compatible storage (AWS, Backblaze B2, R2, MinIO, etc.). They require a backup block in the server config; without it, backup-related commands return 501.
bhatti volume backup workspacebhatti volume backup-list workspacebhatti volume restore workspace --backup-id bk_a1b2c3d4Schedule regular backups with retention via the backup.schedule config — see Configuration.
A named memory snapshot also captures copies of attached volumes; each resume or live fork gets independent volume copies rather than sharing the original volume. A filesystem snapshot captures only the root disk, not attached volumes or the source’s network policy; preserve volume data separately.
See also
Section titled “See also”- Volumes reference — every command
bhatti create --volume— attach syntax- Configuration: backup — S3 setup
- Data & durability — what survives a stop or reboot and how live backups are quiesced