running sandbox, as its own process with its own output, stdin, and exit code. Execs are served by the data plane with a token, never by the control plane.
Running a Command
POST /sandbox/{id}/exec starts a command. The response is 201 with the exec in starting or running. The CLI’s exec starts the command, streams its output, and exits with its exit code.
Output
Workstation
Output
Any number of execs run at once in one sandbox.
A command that cannot start, such as a binary that is not on the image’s
PATH or a workdir that does not exist, is refused with 400 bad_request and the error’s text. No exec is created. A request body over 1 MiB is refused with 413 request_too_large.
Exec Object
Output
Output
GET /sandbox/{id}/exec/{exec_id}/attach upgrades to a WebSocket. The upgrade request carries the token in Authorization. offset starts the stream at a byte offset, and 0 replays from the beginning.
API
Output
Server Messages
Client Messages
A message over 128 KiB closes the socket with
1009, and an unknown type with 1008. Disconnecting never ends the exec and never closes its stdin. A client reattaches with the last offset it received plus the length of that data.
An error before the upgrade, such as 404 or 409 sandbox_paused, is a plain HTTP response.
GET /sandbox/{id}/exec/{exec_id}?wait=10 waits up to 10 seconds for the exec to finish before returning it, for clients that only need the exit code.
The guest keeps the last 8 MiB of each exec’s output, for the 32 most recently finished execs. Output records stay readable until the sandbox terminates.
Stdin
Stdin is written over the exec’s attach WebSocket.POST /sandbox/{id}/exec/{exec_id}/stdin/close sends end-of-file, and answers 202 with the exec, also once the exec has ended. Closing an attach never closes stdin and never ends the exec. A stdin message after stdin is closed receives stdin_closed.
Signals
POST /sandbox/{id}/exec/{exec_id}/kill sends a signal to the exec’s process group. The response is 202 with the exec as it was before the signal, also once the exec has ended.
Request
signal is one of SIGTERM, SIGKILL (default), SIGINT, SIGHUP, SIGQUIT, SIGUSR1, and SIGUSR2. Another name is refused with 400.
PTY
A PTY exec runs a command in a terminal, for shells, editors, REPLs, and programs that behave differently without one. It is an ordinary exec with apty object.
The request below starts a login shell in a terminal of 40 rows and 120 columns.
Request
A PTY merges stdout and stderr into one stream, as a terminal does. Its output arrives as
output messages with stream stdout.
The exec’s attach WebSocket carries keystrokes and screen output.
- Input. Each keystroke or pasted block is a
stdinmessage, base64. - Output. Screen output, including escape sequences, arrives as
outputmessages. - Resize. A
resizemessage changes the terminal size.
Client Messages
resize on an exec without pty is refused. Disconnecting leaves the shell running, and a new attach resumes from any offset the guest still holds.
The shell ends when its process exits, for example after exit is written to stdin. A kill with SIGHUP ends it as a closed terminal would.
List
GET /sandbox/{id}/exec lists the sandbox’s execs, newest first, 20 per page and at most 100. status filters, and repeats.
Execs and Pauses
Execs keep their records across a pause. After a resume, finished execs show their output and exit codes. An exec that was running at the pause readsinterrupted. Its process keeps running in the sandbox, and a kill or a stdin close on the interrupted record answers 202 with the record. An attach that is open when the sandbox pauses keeps receiving heartbeats and is not told. A new attach after the resume receives exit with status interrupted.
Exec requests to a paused sandbox are refused with 409 sandbox_paused. Send connect first.