Skip to main content
Idle sandboxes sleep automatically. Use archive when you want to keep a sandbox for later and release its active slot. Use delete when you are finished with its files and processes. Connect to a sandbox you want to manage:

​
Leave a sandbox idle

An idle sandbox costs you nothing to keep usable: there is no need to poll it or send keep-alive traffic just to hold it ready. It can sleep after about 60 seconds without activity, and a later command or file operation wakes it with its state intact. The 60 seconds count from when the sandbox stops working, not from your last call: after a long command or a background job finishes, the sandbox stays awake for about another minute. A sandbox stays awake while it is doing work: a command is running, its processes are using CPU, it has an open network connection, or a process is waiting on a timer (for example sleep 30 or a scheduled task). A background process that is only waiting, such as a server with no traffic or a worker waiting for input, does not keep it awake: it pauses with the sandbox and continues where it left off when the sandbox wakes. A request to an exposed port wakes a sleeping sandbox. To sleep a sandbox yourself:
A sandbox you sleep and a sandbox the idle policy sleeps are in the same state: the next command wakes it, so your code does not need to know it was asleep. There is no wake call: ANY command or file operation is the wake. After a wake, the reported state can continue to read slept for a few seconds while the platform acknowledges the host. The call that woke the sandbox has already succeeded, so trust its result. If you need the state itself, poll refresh() or get() until it converges rather than treating the first read as final. sleep() returns whether this call put the sandbox to sleep. A busy sandbox — one running foreground work, background processes, or an exposed port — stays awake; archive it instead to stop a busy sandbox. Sleeping sandboxes keep their memory on the host and count toward your organization’s active sandbox limit, and sleep is not a durable checkpoint: use a snapshot or archive to retain recoverable work.

​
Archive and unarchive

Archive a sandbox to save its files, memory, and running processes for later:
If saving takes longer than about 110 seconds, archive() returns while the archive continues, and sandbox.info.state reads archiving. Poll until it reads archived before relying on the archive:
An archived sandbox releases its active slot and retains its saved state. It does not run commands or serve traffic until you explicitly unarchive it:
Processes continue from the saved state. Reconnect external network connections, and allow exposed services a brief reconnect period. Archiving can take longer than sleeping, particularly when there is more state to save.

​
Reboot an unresponsive sandbox

Reboot preserves files but ends processes and shell sessions. Restart any servers you need afterward. Unarchive an archived sandbox before rebooting it.

​
Delete a sandbox

Download results or save a durable snapshot before deleting work you want to keep:
Deletion removes the sandbox’s working state. Its ID can no longer be used to access it, and a repeated delete is safe. Retained snapshots are separate resources; delete them separately when you no longer need them.

​
Set a lifetime

Give a sandbox a lifetime when it must not outlive the job that created it, for example a test run or an agent episode that could crash before its cleanup runs:
One hour after creation the sandbox is deleted, whether it is running, sleeping, or archived, exactly as if you had called delete(). Retained snapshots are kept. Deletion happens within seconds of the deadline, and the sandbox stops counting toward your active sandbox limit.
  • Omit timeout_s for the platform default, which is no lifetime. Pass 0 to ask for none explicitly.
  • The lifetime is fixed when the sandbox is created and counts from then, not from the last activity.
  • Fork copies get the timeout_s you pass to fork(), never their parent’s: sandbox.fork(n=4, timeout_s=600).
  • Values are whole seconds up to 3,153,600,000 (100 years). Anything else raises ValueError in the SDK before a request is sent.
Requires SDK 0.10.2 or later. Over HTTP, send timeout_s in the POST /vms or POST /vms/{id}/branch body; see the HTTP API. See Core concepts for a comparison of states and Recovery for interrupted or unavailable sandboxes.