Skip to content

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 Sandbox handle with commands and files APIs and a few lifecycle methods.
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:`)

Create returns when the sandbox can run commands, typically 6–10 seconds after the call.

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: envs are held by the handle, not stored in the sandbox. They’re added to every command, and per-command envs override them. A handle from connect starts with none unless you pass envs there too.
  • 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.

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 min
sbx.pause() # snapshot memory+disk; resumes on next call
again = Sandbox.connect(sbx.sandbox_id) # from anywhere, later
print(len(Sandbox.list()), "sandboxes")
Sandbox.kill(sbx.sandbox_id) # 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 with chainctl develop aren’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.
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
  • 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.

Each language has a scoped form that kills the sandbox for you:

with Sandbox.create() as sbx: # kill() on exit, even on error
...

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.