Skip to content

Limits and Differences

Simple Chainguard Sandbox SDK runs on Chainguard Workspaces, which is built for long-lived developer sessions. These are the constraints that matter when you use it as a general-purpose sandbox. “Measured” means it was observed against the live service while building this package (November 2026).

Value Notes
Sandboxes per user 1 (beta) A second create fails with LimitReachedError / ErrLimitReached until you kill the first
Sandboxes per organization 3 (beta)
Usage allowance 500 vCPU-hours per month (beta)
Size 4 vCPU, 16 GB RAM, 50–100 GB disk, x86-64 Fixed: no sizing options, no GPUs
Region Chosen by the service Measured: us-east4-eks. Sessions placed on us-east4-plasmad never started, and create retries those automatically

The per-user and per-organization limits are the ones Workspaces applied during its beta, measured with an account on the Starter plan. Other plans may allow more; the service decides, not this package.

Time
create until ready 6–10 s
First command ~1 s
Command on a warm sandbox ~0.15 s round trip
File read/write of 1 MiB ~1.7 s
pause ~40 s until paused
Resume (first call after a pause) ~7 s, up to ~80 s
kill 1–8 s until the slot is free (kill waits for it)
  • One command at a time. Foreground commands in one sandbox run one after another. Concurrent calls queue on the service. Use background commands for parallel work.
  • Background output is polled. Background commands write their output to files in the sandbox, and wait() fetches it about every 2 s. There’s no live stream for a background command.
  • No interactive stdin. stdin is sent up front (at most 16 MiB). You can’t write to a running command.
  • Busy while an interactive shell is attached. Commands fail with SandboxBusyError / ErrBusy while chainctl develop (or another attach) holds the sandbox.
  • No exposed ports or public URLs. Servers inside a sandbox are reachable only from inside it.
  • No container images. The toolchain is a list of Chainguard packages, fixed at create (see Environments).
  • No timeout parameter.
    • An idle sandbox parks (snapshots and stops) after ~10 minutes, and resumes on the next call.
    • A parked sandbox is discarded after 5 days.
    • keep_alive holds a sandbox awake.
    • Always kill sandboxes you’re done with.
  • Root, in /work. Commands run as root; relative paths resolve against /work.
  • Unknown outcomes are possible. If a connection drops before a command reports its exit status, it may or may not have run (OutcomeUnknownError).
  • Python is synchronous. There’s no AsyncSandbox; use threads if you need concurrency across sandboxes.
  • Network:
    • Deny floor: cloud metadata, loopback and private ranges are always blocked. Partly observed: those addresses were refused instantly.
    • Egress allowlists are enforced. Verified: an allowlisted host answered and another was refused.
    • Interception: HTTPS goes through transparent interception with a per-sandbox CA.
  • Files and isolation:
    • Downloads stay in their directory: download_dir refuses archive entries that would land outside the target directory: absolute names, .., and anything reached through a symbolic link. A link that leads outside the directory, directly or through other links, is refused as well. Unit-tested with hostile archives in all four languages; not tested against a hostile sandbox.
    • A microVM per sandbox, and sandboxes belong to the identity that created them. Isolation between identities is the service’s guarantee; this package didn’t test it.

The Workspaces API this package uses is unofficial. It is compatible with chainctl 0.2.398.