Skip to content

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.

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: stdout and stderr chunks arrive as the process writes them, then one exited. The SDK’s on_stdout / on_stderr callbacks 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 exited event, the process may or may not have run. The SDK reports OutcomeUnknownError and doesn’t retry.

The SDK never sends your command as-is. It wraps it so the working directory and environment variables apply:

argv[0] sh
argv[1] -c
argv[2] cd -- "$1" 2>/dev/null || { echo "sandbox: no such directory: $1" >&2; exit 47; }; shift; exec "$@"
argv[3] _
argv[4] /work the working directory
then env K1=V1 K2=V2 only when there are environment variables
then bash -lc 'npm test' a string command (a list is passed as-is)
  • Working directory: cwd, or /work by default (relative paths resolve against /work). A missing directory exits with the reserved code 47 and the message above, which the SDK turns into FileNotFoundError.
  • Environment: the sandbox’s envs plus the call’s envs, sorted by name and applied with env. 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: timeout becomes deadline. When it passes, the service kills the process and sends exited with timed_out = true; the SDK raises TimeoutError with the output so far.

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.

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 Exec waits up to 10 s for the shell’s lease, then fails with ABORTED (“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 Exec resumes it, taking 7–80 s.