Core concepts
An isolated Linux VM your agent works in
Created with Sandbox.create(), lives until its timeout or kill(). Has its own filesystem, processes, network rules and a public URL per port. Continuous runtime is capped at 1 hour on Hobby and 24 hours on Pro.
The image a sandbox boots from
Defined in code, built with the V2 build system. A template is a snapshot taken at build time, so the processes its start command launched are already running when a sandbox boots.
A checkpoint of a running sandbox
Captures filesystem and memory. Any number of new sandboxes can be created from it while the original keeps running. Needs templates with envd v0.5.0 or newer.
One sandbox, frozen and kept
pause() saves filesystem and memory; connect() resumes it exactly as it was. Kept indefinitely and never counted against your concurrency limit.
Storage that outlives sandboxes
Mounted at a path in one or many sandboxes, or used directly through the SDK. Private beta.
A credential the sandbox never sees
Stored write-only at the project level and injected into outbound HTTPS requests by the egress proxy. Private beta.
Snapshot, pause or fork?#
| You want to… | Use | Why |
|---|---|---|
| Stop paying for an idle sandbox and come back later | Pause | Same sandbox ID, state kept indefinitely |
| Try several approaches from the same point, right now | Fork | Up to 100 running copies in one call |
| Keep a checkpoint to start from again and again | Snapshot | Persistent, one-to-many, original keeps running |
| Make every sandbox start with your stack preinstalled | Template | Compact memory and prefetching make templates the faster boot |