Background
How It Works
Simple Chainguard Sandbox SDK is a thin layer over the Chainguard Workspaces Sessions API, the gRPC service
chainguard.sandbox.runtime.session.v1.Sessions at sessions.chainbox.dev that chainctl develop uses.
This page shows what each call does there. The simple sandboxing API doesn’t describe the full Workspaces sandboxing protocol.
The Protocol section documents the messages and fields on the wire.
The Big Picture
Section titled “The Big Picture”- On your machine: your program calls the library. The library keeps one saved login, shared by the Go, Python, TypeScript and Rust packages, and opens the browser only when there’s no valid login.
- At Chainguard:
issuer.enforce.devturns the login into short-lived tokens.sessions.chainbox.devis the only API that touches sandboxes. The account API is asked only to find your organization when you haven’t named one. - On the sandbox host: each sandbox is its own microVM. Its outbound traffic goes through a proxy that applies your egress allowlist on top of a fixed deny floor (cloud metadata, loopback and private ranges).
A Sandbox Is a Session
Section titled “A Sandbox Is a Session”| Simple Chainguard Sandbox SDK | Workspaces API |
|---|---|
| choosing the organization | explicit option, else $CHAINCTL_SANDBOX_INSTANCE, else GET console-api.enforce.dev/iam/v1/groups?uidp.in_root=true (account API) and the only organization |
create |
CreateSession with a workspace source, then GetSession polling until the guest starts, then one short AttachSession (below) |
create with source |
CreateSession with a repository source (the service clones it) |
connect, list |
GetSession / ListSessions (filtered by workspace label /chainguard-sandbox/<name>) |
kill |
DeleteSession, then GetSession until it’s gone |
pause |
UpdateSession with park_request = PARK |
keep_alive |
HeartbeatSession(hold_for) |
get_info |
GetSession (phase → state) |
| commands, files | Exec |
Creating a Sandbox
Section titled “Creating a Sandbox”- Environment document: your packages and egress policy are written as an environment document (see
Environments), and the sandbox is created as a workspace session with label
/chainguard-sandbox/<name>. - Waiting: the session boots a microVM. The package polls
GetSessionabout once a second untilguest_started_timeis set. If the service reportsstarting guest failed … process handoffs do not support usage assignmentsfor over 30 s, the session landed on a bad host. It’s deleted and recreated, up to 3 attempts. - First upload: a workspace session expects its files to be uploaded on the first interactive attach,
and the service refuses
Execuntil then (attach with a shell first to upload the workspace). A forwarding-only attach doesn’t count either (open.endpoints: required for a no_shell attach). So the package opens one shortAttachSession, uploads an empty tree (a 1 KiB empty tar), waits forworkspace_ready, and detaches. That takes about 0.2 s. - Ready: from then on everything is
Exec.
Commands and Files Are Programs Run Over Exec
Section titled “Commands and Files Are Programs Run Over Exec”Exec(argv, stdin, deadline) runs one process and streams its stdout and stderr, then the exit status.
Simple Chainguard Sandbox SDK builds everything on it:
| Call | What runs in the sandbox |
|---|---|
commands.run("…") |
sh -c 'cd -- "$1" … exec "$@"' _ <cwd> env K=V … bash -lc "…" |
commands.run([...]) |
the same wrapper, then your argv |
run(…, background) |
a script that starts the command with setsid (its own process group), sends output to /tmp/.chainguard-sandbox/cmd/<id>/{stdout,stderr}, records pid and later exit, and returns the pid |
handle.wait() / poll() |
a script that waits up to 2 s for exit, then returns the exit status and the new bytes of stdout and stderr since the last offsets |
handle.kill() |
kill -s KILL -- -<pgid>, waits for exit, and records 137 |
files.read |
cat (with checks that map to not-found / is-a-directory errors) |
files.write |
write a temp file and rename it into place; over 15 MiB, staged in 15 MiB pieces first |
files.write([...]), upload_dir |
one gzip’d tar, unpacked with tar -xzf |
files.list, get_info |
stat -c '%s %a %U %G %Y' per entry |
download_dir |
tar -czf - -C <dir> ., unpacked locally with path checks |
Running a Command
Section titled “Running a Command”Background Commands
Section titled “Background Commands”- Shared scripts: the scripts are POSIX
shplus busybox/coreutils tools, so they work with any package list. They’re byte-identical in the four languages: Go is the source, and the SDK’sscripts/gen_sandbox_scripts.pygenerates the Python, TypeScript and Rust copies. - Why one command at a time: each Exec takes the sandbox’s lease, so concurrent Execs queue, and none can run while an interactive shell holds it.
- Why background commands use files: a background command doesn’t hold a connection. Its output is fetched by short polls.
- Why 15 MiB pieces: a single Exec carries at most 16 MiB of stdin.
Parking and Resuming
Section titled “Parking and Resuming”The states are the values of get_info().state, with the Workspaces phase behind each; a deleted sandbox
no longer exists.
pause asks the service to park the session: a full memory and disk snapshot. Processes,
including background commands, and /tmp survive. Any later Exec resumes the session first; that’s done
by the service, not this package. Idle sessions also park on their own after ~10 minutes.
Authentication
Section titled “Authentication”Every call carries a bearer token for audience https://sessions.chainbox.dev, minted from the libraries’
saved browser login. Organization auto-detection uses a second token, for the account API
(https://console-api.enforce.dev), from the same login. See
Authentication and Organizations.
