Skip to main content
Sailboxes preserve their writable disk, in-memory state, and in-flight network requests across checkpoints and resumes. 
sb.checkpoint()  # Snapshot while keeping the Sailbox running
child = sb.fork(name="rollout-1")  # Branch memory and writable disk into a new Sailbox
sb.pause()       # Checkpoint and pause until explicit resume
sb.sleep()       # Checkpoint and sleep until network ingress, exec, or resume
sb.resume()      # Resume a paused or sleeping Sailbox
sb.upgrade()     # Update the in-guest Sail agent by rebooting on the same disk
sb.terminate()   # Permanently destroy the Sailbox

​
Checkpoint

checkpoint() snapshots VM memory and writable disk while keeping the Sailbox running: 
sb.exec("python3 setup.py").wait()
sb.checkpoint()
Call checkpoint() after important setup, such as installing packages, fetching remote data, or writing files. On host failure, Sail restores from the most recent completed checkpoint and does not replay commands that ran before that checkpoint.

​
Fork

fork() creates a separate running Sailbox from the current in-memory process state and writable disk: 
child = sb.fork(name="experiment-1")
The child gets new Sail identity and networking. Active TCP connections are reset in the child. A fork starts with no inherited ingress, so add the ports the child should publish with expose. Sleeping and paused Sailboxes can be forked too: the child boots from the parent’s last checkpoint without waking the parent. Forking a running Sailbox snapshots only the changes since its last checkpoint, so forks of frequently checkpointed Sailboxes are fast.

​
Pause

pause() checkpoints the Sailbox and powers it down until you explicitly resume it: 
sb.pause()
sb.resume()
Use pause when you want to preserve state but do not want the Sailbox to wake on network traffic.

​
Sleep

sleep() checkpoints the Sailbox and powers it down until network ingress, exec, or an explicit resume wakes it: 
sb.sleep()
Use sleep for idle services that should wake when they receive traffic.

​
Sleep during inference

To automatically sleep a Sailbox while a foreground Sail inference call is in flight, include its ID in the request with the X-SailboxId header. Sail will resume the Sailbox after the inference call completes. 
response = client.responses.create(
    model="zai-org/GLM-5",
    input="Summarize the current workspace state.",
    background=False,
    extra_headers={"X-SailboxId": sb.sailbox_id},
)

​
Resume

resume() restores a paused or sleeping Sailbox and returns an updated handle: 
sb = sb.resume()
Sailbox.connect() also verifies placement and resumes a paused or sleeping Sailbox before returning: 
sb = sail.Sailbox.connect("sb_...")

​
Upgrade

upgrade() reboots the Sailbox on its same disk onto the latest in-guest Sail agent, picking up new features, fixes, and performance improvements without recreating the Sailbox: 
applied = sb.upgrade()

sail box upgrade <id>
The filesystem is fully preserved; running processes stop and the Sailbox boots fresh, like a machine reboot. Restart any long-running services afterwards. On a running Sailbox the upgrade applies immediately and upgrade() returns True. On a paused or sleeping Sailbox the upgrade is recorded without waking it and upgrade() returns False; it applies automatically the next time the Sailbox wakes. A Sailbox that is already on the current agent version returns True without rebooting. A Sailbox whose agent is too old for the current platform to resume safely is upgraded automatically the next time it wakes, as if upgrade() had been called on it first. Each Sailbox reports its agent version as guest_schema_version, and listing supports a max_guest_schema_version filter to find Sailboxes that still need an upgrade.

​
Terminate

terminate() permanently destroys the Sailbox: 
sb.terminate()
Termination is not reversible. Use pause() or sleep() when you want to keep the VM state for later.