Protocol
Exec
Exec runs one process in the sandbox and streams its output back. Every command and every file
operation in the SDK is an Exec call.
Messages
Section titled “Messages”rpc Exec (ExecRequest) returns (stream ExecResponse);
message ExecRequest { string name = 1; // required: the session repeated string argv = 2; // required: no shell is implied bytes stdin = 3; // sent up front; at most 16 MiB google.protobuf.Duration deadline = 4; // the process is killed when it passes}
message ExecResponse { oneof event { bytes stdout = 1; bytes stderr = 2; Exited exited = 3; // always the last event }
message Exited { int32 code = 1; // the exit status bool timed_out = 3; // killed at the deadline }}- One request, a stream of events:
stdoutandstderrchunks arrive as the process writes them, then oneexited. The SDK’son_stdout/on_stderrcallbacks see each chunk. - stdin: the whole input goes in the request and is closed after it. There’s no way to write to a running process. The SDK checks the 16 MiB limit before sending.
- No cwd or environment fields: the SDK wraps the command to set them (below).
- Lost outcome: if the stream ends without an
exitedevent, the process may or may not have run. The SDK reportsOutcomeUnknownErrorand doesn’t retry.
How the SDK Builds argv
Section titled “How the SDK Builds argv”The SDK never sends your command as-is. It wraps it so the working directory and environment variables apply:
argv[0] shargv[1] -cargv[2] cd -- "$1" 2>/dev/null || { echo "sandbox: no such directory: $1" >&2; exit 47; }; shift; exec "$@"argv[3] _argv[4] /work the working directorythen env K1=V1 K2=V2 only when there are environment variablesthen bash -lc 'npm test' a string command (a list is passed as-is)- Working directory:
cwd, or/workby default (relative paths resolve against/work). A missing directory exits with the reserved code 47 and the message above, which the SDK turns intoFileNotFoundError. - Environment: the sandbox’s
envsplus the call’senvs, sorted by name and applied withenv. They’re kept client-side and sent with every call. - Shell or not: a string command runs with
bash -lc; a list runs as argv, with no shell. - Timeout:
timeoutbecomesdeadline. When it passes, the service kills the process and sendsexitedwithtimed_out = true; the SDK raisesTimeoutErrorwith the output so far.
Commands and Files as Scripts
Section titled “Commands and Files as Scripts”Background commands and file operations run small POSIX sh scripts through the same wrapper. They’re
the same in all four SDKs:
| SDK call | What the script does in the sandbox |
|---|---|
commands.run(…, background) |
starts the command with setsid, sends its output to /tmp/.chainguard-sandbox/cmd/<id>/, and prints the pid |
handle.wait(), poll() |
waits up to 2 s for the exit file, then prints the exit status and the output since the last offsets |
handle.kill() |
kill -s KILL to the process group, then records exit code 137 |
files.read |
cat, after checking the path exists and is a file |
files.write |
writes stdin to a temp file and renames it into place |
files.write over 15 MiB |
one Exec per 15 MiB piece, appended to a staging file, then one that moves it into place |
files.write([...]), upload_dir |
tar -xzf - of a gzip’d tar sent as stdin |
files.list, get_info, exists |
stat per entry |
download_dir |
tar -czf - streamed back as stdout |
The scripts use reserved exit codes: 44 “not found”, 45 “is a directory” and 46 “not a directory”, which
the SDK maps to FileNotFoundError and InvalidPathError.
One Exec at a Time
Section titled “One Exec at a Time”Each Exec takes the session’s lease (held_until moves to about 90 s after the call), so execs on one
sandbox run one after another; concurrent calls queue on the service.
- While a shell is attached: an
Execwaits up to 10 s for the shell’s lease, then fails withABORTED(“busy: the guest is held elsewhere … nothing ran”):SandboxBusyError. - Right after another attach or exec: the service can answer
FAILED_PRECONDITION(“instance held by another controller” or “Channel already in use”) for a few seconds. Nothing ran, so the SDK retries after 2, 4, 8, 8 and 8 s (about 30 s in all). - A parked sandbox: the first
Execresumes it, taking 7–80 s.
