Skip to content

Data & durability

A sandbox has a root disk, optional attached volumes, and running memory. I choose the recovery boundary before putting important work in one: stop keeps disks, not processes; a named memory snapshot is what keeps a running process state.

EventFiles on root diskAttached volumesProcesses and /tmp
bhatti stop, then startKeptKept and re-attachedLost; guest boots again
Thermal warm pauseKeptKeptPaused in mapped memory; resumed on request
Thermal cold power-offKeptKeptLost; next request cold-boots
Named snapshot create (default memory)CopiedCopied; new copies attached on resumeCaptured and continued on resume
snapshot create --type filesystemCopiedNot captured; preserve separatelyNot captured; resume cold-boots
Daemon restart/updateKeptKeptRunning v2.4+ VMs can be adopted if their helpers survive; otherwise disk recovery, not a process guarantee
Host reboot or unexpected power lossKept if flushed to storageKept if flushed/backed upLost without an explicit memory snapshot

Stop and thermal cold are power-offs, not hidden full-memory checkpoints. The guest’s ephemeral /tmp and one-shot jobs go away; create with --init for work that must start again on cold boot. --keep-hot is useful for active connections, but it is not a backup or a host power-loss guarantee. External TCP peers will not necessarily keep a connection even when you restore a named memory snapshot.

Ordinary bhatti exec no longer forces a guest-wide sync after every command. If your agent writes a file and needs it on disk before acknowledging success, opt in:

Terminal window
bhatti exec dev --sync -- ./write-important-data

The API equivalent is POST /sandboxes/:id/exec with "sync": true. The guest sync runs before command completion is reported. --sync and --detach cannot be combined. Recent servers also sync before pausing a guest; a warm stop wakes and syncs before powering off. The guest limits dirty writeback to about five seconds. If synchronization fails at a stop boundary, the server emits sandbox.unclean_stop; inspect it with bhatti admin events --type sandbox.unclean_stop and check the affected filesystem before trusting the stopped state. None of these replaces an off-host backup in the face of disk loss.

Sandboxes created before v2.4 retain an older lohar inside their image. Newer guest capabilities, including grant handling, fork or root-disk growth, can return 409 asking you to recreate the sandbox; after updating the server, recreate old sandboxes to get the full guest-side durability behavior.

The root disk is a private copy-on-write overlay; destroying the sandbox deletes it. Persistent volumes survive sandbox destruction and can be attached at create time with --volume workspace:/workspace. Stopping does not detach them: volume resize, clone, and restore require zero attachments, so a stopped sandbox still blocks those operations. A volume is not automatically an off-site backup. Choose volume backup for S3-compatible storage; restoring a backup requires a volume unattached to every sandbox.

You can back up a volume while the guest is running. The server holds its lifecycle, quiesces each running attachment, copies the volume locally, then releases the guest before compression/upload. New agents freeze/thaw the guest filesystem (consistency_mode: frozen); older agents sync only (sync_only); a volume with no running attachments (including one attached to a stopped sandbox) records detached. Historical backups without a recorded consistency mode can show unverified. Sync-only does not protect concurrent writers as strongly as a frozen filesystem. The full API backup record has consistency_mode; the CLI backup-list table and its JSON representation currently show only ID, size, and creation time. Schedule backups and check a restore path instead of assuming a local copy will survive host failure.

A named memory snapshot captures RAM, CPU state, the root disk, attached-volume copies and network policy; each resumed sandbox gets cloned, re-attached volume copies. A filesystem snapshot captures only the root disk and cold-boots a fresh sandbox without the source’s volumes or network policy; preserve volume data separately. Snapshots are for branching or restoring a particular state; export/import carries that checkpoint to a compatible host, not a substitute for independently backed-up application data.