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).
Capacity
Section titled “Capacity”| 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.
Speed (Measured)
Section titled “Speed (Measured)”| 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) |
Behavior
Section titled “Behavior”- 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/ErrBusywhilechainctl 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_aliveholds a sandbox awake.- Always
killsandboxes 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.
Security Properties
Section titled “Security Properties”- 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_dirrefuses 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.
- Downloads stay in their directory:
API Stability
Section titled “API Stability”The Workspaces API this package uses is unofficial. It is compatible with chainctl 0.2.398.
