Skip to main content

​
Sandboxes

A sandbox is an isolated Linux environment with its own files, installed packages, and running processes. Use it to run a task, host a development service, or give a coding agent a workspace. Every sandbox has an ID. Save that ID if you want to reconnect from another script:
Files remain between commands. A regular run() starts a new shell, so use a session when you need a working directory or environment variables to carry over.

​
Images and templates

An image defines the software your sandbox starts with. Use the default image or provide an OCI image reference, such as python:3.12-slim. A template is a reusable starting environment prepared from an image with a chosen CPU, memory, and runtime configuration. Create a named template when you want to prepare an environment ahead of time and reuse it across tasks. A sandbox created from a template or snapshot uses that source’s CPU and memory configuration. See Custom images for setup examples.

​
Snapshots and forks

A snapshot saves a sandbox’s files, memory, and running processes at a point in time. Restore it to create a new sandbox from that checkpoint. Snapshots remain available after you delete the original sandbox. A fork creates one or more independent copies of a sandbox’s current state. Use forks to compare approaches, run tests in parallel, or give several agents the same starting environment. Changes in one copy do not change the others. See Save, restore, fork for examples and guidance on processes and network connections.

​
Rest states

Idle sandboxes sleep automatically. Servers and background jobs keep a sandbox awake while they are active. Archive a sandbox when you want to keep it for later and release its active slot; delete it when you no longer need its working state.

​
Durability rules

A snapshot marked durable has finished saving and can be used for recovery if the original sandbox becomes unavailable. Use snapshot(wait_durable=True) when saving a checkpoint you intend to keep. A snapshot may be restorable before it is durable, but it is not yet protected against loss of the original environment. Archived sandboxes also retain their saved state for recovery. Pausing and sleeping preserve your current session but do not create a recovery checkpoint. Rebooting preserves files and restarts the environment; running processes and shell sessions are lost. Deleting a sandbox preserves only separately retained snapshots and exports. See Manage sandbox lifecycle for the relevant commands.