Skip to content

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.

Sandbox host

Chainguard

Your machine

opens on first login

log in

refresh

list organizations

create, exec, pause, kill

boot, run, park, resume

Your program

Simple Chainguard Sandbox SDK
Go, Python, TypeScript or Rust

Saved login
login.json

Browser

issuer.enforce.dev
login and token refresh

console-api.enforce.dev
organization lookup, optional

sessions.chainbox.dev
Sessions API, gRPC

Your sandbox: a microVM
root in /work, your packages

Egress proxy
allowlist and deny floor

Internet

  • 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.dev turns the login into short-lived tokens. sessions.chainbox.dev is 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).
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
Sandbox (microVM)Sessions APISimple ChainguardSandbox SDKYour programloop[about once a second]A session stuck on a bad host for over 30 s is deleted and recreated, up to 3 attemptsSandbox.create(packages, envs, egress)1CreateSession with a workspace source and an environment document2boot a microVM with your packages3GetSession4phase CREATING, until guest_started_time is set5AttachSession: open a shell6upload an empty workspace (a 1 KiB tar)7workspace_ready8detach9Sandbox, ready for commands and files10
  1. 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>.
  2. Waiting: the session boots a microVM. The package polls GetSession about once a second until guest_started_time is set. If the service reports starting guest failed … process handoffs do not support usage assignments for over 30 s, the session landed on a bad host. It’s deleted and recreated, up to 3 attempts.
  3. First upload: a workspace session expects its files to be uploaded on the first interactive attach, and the service refuses Exec until 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 short AttachSession, uploads an empty tree (a 1 KiB empty tar), waits for workspace_ready, and detaches. That takes about 0.2 s.
  4. 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
SandboxSessions APISimple ChainguardSandbox SDKYour programloop[while it runs]alt[exit code 0][any other exit code]commands.run("npm test", cwd, envs, timeout)1Exec(sh wrapper, stdin, deadline)2cd to cwd, set the env, run bash -lc "npm test"3stdout and stderr bytes4output chunks5on_stdout and on_stderr callbacks6exit status7exit status8CommandResult with exit_code, stdout and stderr9CommandExitError, carrying the same result10
SandboxSessions APISimple ChainguardSandbox SDKYour programThe command keeps running between calls and across pausesloop[until the command has exited]commands.run("./server", background=True)1Exec(start script)2setsid ./server, output to files in /tmp/.chainguard-sandbox/cmd/3pid4CommandHandle, at once5handle.wait(on_stdout)6Exec(poll script, waits up to 2 s)7read the output since the last offsets8new stdout and stderr, and the exit code once it has exited9callbacks with the new output10CommandResult, or CommandExitError11

no

yes

files.write(path, data)

over 15 MiB?

one Exec: the data as stdin,
written to a temp file, renamed into place

one Exec per 15 MiB piece,
appended to a staging file

one Exec: the staging file
is moved into place

files.write([...]) or upload_dir

one gzip'd tar as stdin
(staged the same way if large)

one Exec: tar -xzf
into the target directory

download_dir

one Exec: tar -czf -
streamed back as stdout

unpacked on your machine,
refusing entries outside the target

  • Shared scripts: the scripts are POSIX sh plus 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’s scripts/gen_sandbox_scripts.py generates 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.

create()

guest started, 6 to 10 s

pause(), or about 10 min idle

any call resumes it, 7 to 80 s

kill()

kill(), or 5 days parked

creating
phase CREATING

running
phase ATTACHED or IDLE

paused
phase PARKED: a memory
and disk snapshot

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.

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.

Sessions APIissuer.enforce.devBrowserSaved loginSimple ChainguardSandbox SDKalt[no saved login, or it expired (unused for 20 h)]The token is reused until a minute before it expires, then refreshed the same wayread the saved refresh token1open the issuer's login page2you log in with GitHub, Google or GitLab3redirect to a localhost callback with a token and a refresh token4save the refresh token5POST /sts/exchange_refresh_token?aud=sessions.chainbox.dev6a short-lived token and a new refresh token7save the new refresh token (the old one is now spent)8gRPC calls with Authorization: Bearer token9

not set

not set

set

set

exactly one

several, or none

turned off with
CHAINGUARD_SANDBOX_NO_DETECT_INSTANCE=1

1. instance set in code

2. CHAINCTL_SANDBOX_INSTANCE
environment variable

3. auto-detect: ask the account API
which organizations you belong to

use that organization

error that lists
your organizations

error: no instance configured