Guides
Sandboxes
A sandbox is a Linux microVM with your packages, a working directory (/work) and a lifecycle.
- Creating one: it starts a Chainguard Workspaces session, as described in How it works.
- The handle: you get a
Sandboxhandle withcommandsandfilesAPIs and a few lifecycle methods.
Creating a Sandbox
Section titled “Creating a Sandbox”sbx = Sandbox.create( name="data-job", # display name "data-job/<word-word>" packages=["bash", "coreutils", "python-3.12"], # Chainguard package names envs={"MODE": "test"}, # for every command egress=["pypi.org", "files.pythonhosted.org"], # instance="XXXXXX", # organization ID; else $CHAINCTL_SANDBOX_INSTANCE, else auto-detected)print("sandbox", sbx.sandbox_id)# ... and sbx.kill() when done (or use `with Sandbox.create(...) as sbx:`)const sbx = await Sandbox.create({ name: "data-job", // display name "data-job/<word-word>" packages: ["bash", "coreutils", "python-3.12"], // Chainguard package names envs: { MODE: "test" }, // for every command egress: ["pypi.org", "files.pythonhosted.org"], // instance: "XXXXXX", // organization ID; else $CHAINCTL_SANDBOX_INSTANCE, else auto-detected});console.log("sandbox", sbx.sandboxId);// ... and await sbx.kill() when done (or `await using sbx = ...`)sb, err := sandbox.Create(ctx, &sandbox.CreateOptions{ Name: "data-job", // display name "data-job/<word-word>" Packages: []string{"bash", "coreutils", "python-3.12"}, // Chainguard package names Envs: map[string]string{"MODE": "test"}, // for every command Egress: []string{"pypi.org", "files.pythonhosted.org"}, // Instance: "XXXXXX", // organization ID; else $CHAINCTL_SANDBOX_INSTANCE, else auto-detected})if err != nil { return err}defer sb.Kill(context.Background())fmt.Println("sandbox", sb.ID)let sbx = Sandbox::create(CreateOptions { name: "data-job".into(), // display name "data-job/<word-word>" packages: Some( ["bash", "coreutils", "python-3.12"] .map(String::from) .to_vec(), ), // Chainguard package names envs: HashMap::from([("MODE".into(), "test".into())]), // for every command egress: Some(vec!["pypi.org".into(), "files.pythonhosted.org".into()]), // instance: "XXXXXX".into(), // organization ID; else $CHAINCTL_SANDBOX_INSTANCE, else auto-detected ..Default::default()}).await?;println!("sandbox {}", sbx.id);// ... and sbx.kill().await when done (or use Sandbox::with, which deletes it for you)Create returns when the sandbox can run commands, typically 6–10 seconds after the call.
Options
Section titled “Options”| Option | Python | TypeScript | Go | Rust | Default |
|---|---|---|---|---|---|
| Packages to install | packages= |
packages |
Packages |
packages: Some(..) |
DEFAULT_PACKAGES: bash, coreutils, curl, git, jq, python-3.13, nodejs-22 |
| Environment variables for every command | envs= |
envs |
Envs |
envs |
none |
Name (display name <name>/<word-word>) |
name= |
name |
Name |
name |
"sandbox" |
| Outbound allowlist | egress= |
egress |
Egress |
egress: Some(..) |
["*"] (open) |
| Outside the allowlist | egress_policy= |
egressPolicy |
EgressPolicy |
egress_policy |
"deny" |
| Full environment document | document= |
document |
Document |
document: Some(..) |
generated |
| Start from a GitHub repo | source=, source_revision= |
source: {url, revision} |
Source: &GitSource{URL, Revision} |
source: Some(GitSource { url, revision }) |
empty /work |
| Wait for the guest | start_timeout= (s) |
startTimeoutMs |
StartTimeout |
start_timeout: Some(Duration) |
3 minutes. A hard limit on the wait: a stalled status call is cut off when it passes, and the sandbox is deleted |
| Organization ID | instance= |
instance |
Instance |
instance |
$CHAINCTL_SANDBOX_INSTANCE, else auto-detected (details) |
| Existing client | client= |
client |
Client |
client: Some(..) |
a new one with the default login |
- Packages, egress and documents: see Environments and network.
- Environment variables:
envsare held by the handle, not stored in the sandbox. They’re added to every command, and per-commandenvsoverride them. A handle fromconnectstarts with none unless you passenvsthere too.
What Can Go Wrong
Section titled “What Can Go Wrong”- An unknown package fails create with the resolver’s message, before a sandbox exists.
- Session limit: if your organization is at its session limit (one sandbox per user and three per organization during the beta),
create raises
LimitReachedError(Go:ErrLimitReached, Rust:Error::LimitReached). Kill an existing sandbox first. - Host failures: the service sometimes places a session on a host that never starts it. Create detects this, deletes the session, and tries again (up to 3 attempts). If create fails for any reason, nothing is left behind.
Finding and Reconnecting
Section titled “Finding and Reconnecting”Sandboxes live on the service, not in your process. Any process logged in to the same organization can reconnect by ID:
info = sbx.get_info()print(info.state, info.region, info.cpu_count, info.memory_mb)sbx.keep_alive(30 * 60) # don't park while idle for 30 minsbx.pause() # snapshot memory+disk; resumes on next call
again = Sandbox.connect(sbx.sandbox_id) # from anywhere, laterprint(len(Sandbox.list()), "sandboxes")Sandbox.kill(sbx.sandbox_id) # by ID (or sbx.kill())const info = await sbx.getInfo();console.log(info.state, info.region, info.cpuCount, info.memoryMB);await sbx.keepAlive(30 * 60_000); // don't park while idle for 30 minawait sbx.pause(); // snapshot memory+disk; resumes on next call
const again = await Sandbox.connect(sbx.sandboxId); // from anywhere, laterconsole.log((await Sandbox.list()).length, "sandboxes");await Sandbox.kill(sbx.sandboxId); // by ID (or sbx.kill())info, _ := sb.GetInfo(ctx)fmt.Println(info.State, info.Region, info.CPUs, info.MemoryMiB)sb.KeepAlive(ctx, 30*time.Minute) // don't park while idle for 30 minsb.Pause(ctx) // snapshot memory+disk; resumes on next call
again, _ := sandbox.Connect(ctx, sb.ID, nil) // from anywhere, laterdefer again.Close()list, _ := sandbox.List(ctx, nil)fmt.Println(len(list), "sandboxes")sandbox.Kill(ctx, sb.ID, nil) // by IDlet info = sbx.get_info().await?;println!( "{} {} {} {}", info.state, info.region, info.cpus, info.memory_mib);sbx.keep_alive(Duration::from_secs(30 * 60)).await?; // don't park while idle for 30 minsbx.pause().await?; // snapshot memory+disk; resumes on next call
let again = Sandbox::connect(&sbx.id, ConnectOptions::default()).await?; // from anywhere, laterprintln!( "{} sandboxes", chainguard_sandbox::list(ConnectOptions::default()) .await? .len());chainguard_sandbox::kill(&sbx.id, ConnectOptions::default()).await?; // by ID (or sbx.kill())connect(id)accepts the short ID (sandbox_id/sandboxId/ID/id, 8 hex characters), the display name, or the full resource name.list()returns the sandboxes this package created. They’re marked by their workspace label, so sessions you opened withchainctl developaren’t included.kill(id)on the class (Go:sandbox.Kill(ctx, id, nil), Rust:chainguard_sandbox::kill(id, ..)) deletes by ID and returns false if there was no such sandbox. It doesn’t attach to the sandbox first, so it also removes one that never started or can’t be attached to.
Lifecycle
Section titled “Lifecycle”create ──▶ running ──(idle ~10 min, or pause())──▶ paused ──(any call)──▶ running │ │ └──────────────── kill() ────────────────┴──▶ gone (also: paused 5 days)| Method | Python | TypeScript | Go | Rust | Notes |
|---|---|---|---|---|---|
| Delete | kill() |
kill() |
Kill(ctx) |
kill() |
Returns once the sandbox is gone (deletion takes 1–8 s), so you can create the next one immediately. False if it was already gone. If the sandbox still exists after 30 s, or that can’t be confirmed, it fails with TimeoutError (Go: *TimeoutError with Op: "kill", Rust: Error::Timeout with op “kill”): deletion was requested but the slot may not be free yet |
| Snapshot and stop | pause() |
pause() |
Pause(ctx) |
pause() |
Memory + disk snapshot. Processes, files in /tmp and background commands survive. The next command or file call resumes it |
| Stay awake | keep_alive(seconds) |
keepAlive(ms) |
KeepAlive(ctx, d) |
keep_alive(Duration) |
Holds the sandbox running instead of parking it when idle |
| State | get_info(), is_running() |
getInfo(), isRunning() |
GetInfo(ctx), IsRunning(ctx) |
get_info(), is_running() |
state is creating, running, paused or stopped. Also region, CPUs, memory, created and expiry times |
| Release the handle | close() |
— | Close() |
— (drop it) | Closes the connection the handle opened. The sandbox keeps running |
Timing (Measured)
Section titled “Timing (Measured)”- Create: 6–10 s.
- First command: about 1 s, then about 0.15 s per command.
- Pause: about 40 s.
- Resume: about 7 s after a pause; up to about 80 s after an explicit pause on a busy host.
Cleanup
Section titled “Cleanup”Each language has a scoped form that kills the sandbox for you:
with Sandbox.create() as sbx: # kill() on exit, even on error ...await using sbx = await Sandbox.create(); // kill() at the end of the scopesb, err := sandbox.Create(ctx, nil)if err != nil { return err }defer sb.Kill(context.Background())Sandbox::with(CreateOptions::default(), async |sbx| { // kill() when the closure returns, even on error // ... Ok(())}).await?;A Sandbox from Sandbox::create is not deleted when it’s dropped (Rust has no asynchronous drop):
call sbx.kill().await. The blocking module’s Sandbox does delete on drop.
There’s no sandbox timeout parameter. A forgotten sandbox parks after about 10 idle minutes, and is discarded after 5 days parked. Until it’s gone it can still count against your session limit: the service’s own message says to “wait for an idle one to be parked and reaped”. So kill sandboxes explicitly.
