Skip to main content
The commands API runs on the sandbox data plane and lets you execute processes directly inside a Firecracker microVM. It offers two execution modes: run-to-completion for short commands where you want the output returned in a single response, and background processes for long-running workloads where you need to stream output or send input interactively. All commands endpoints use the sandbox-specific data plane base URL:
Authenticate every request with a capability token in the X-Sandbox-Token header. See Tokens to learn how to mint one.
The data plane is available whenever the sandbox is running, even if the control plane is temporarily unavailable. Capability tokens carry all the information the gateway needs to verify the request without phoning home.

​
POST /commands

Runs a command inside the sandbox and blocks until the command exits or the timeout elapses. Output is captured and returned in a single JSON document. If the output exceeds the capture limit, the truncated flag is set to true. Use this endpoint for short, discrete commands. For commands with unbounded output, interactive sessions, or PTY requirements, use POST /processes and the streaming API instead.
Request body
​
string
required
The program to run. Use an absolute path or a name resolvable on $PATH inside the sandbox.
​
string[]
Arguments passed to the command. Up to 256 entries.
​
string
Working directory for the command. Omit to use the default user’s home directory.
​
object
Additional environment variables set for this command only. Keys and values are strings. These are merged with the process environment; they do not replace it.
​
string
Bytes written to the command’s stdin before it is closed. Use this for commands that read from stdin without being interactive.
​
integer
Kill the command if it has not exited after this many seconds. Omit to use the agent’s default timeout.
Response — 200 OK The command ran. Check exit_code to determine success or failure.
​
integer
required
The command’s exit code. Zero means success. A negative value means the command was killed by a signal.
​
string
required
Standard output captured from the command.
​
string
required
Standard error captured from the command.
​
boolean
True when the output exceeded the agent’s capture limit. The captured portion is still returned. If you need the full output, use the streaming API instead.
Error codes: 400 malformed request · 401 unauthenticated or expired token · 408 timeout elapsed (command was killed) · 429 per-sandbox concurrent-connection cap reached

​
POST /processes

Starts a supervised background process and returns as soon as it has been spawned. The process continues running after your HTTP request completes. Attach to its WebSocket stream for live output, stdin, signals, and PTY resize events.
Request body
​
string
required
The program to run.
​
string[]
Arguments passed to the command. Up to 256 entries.
​
string
Working directory. Omit to use the default user’s home directory.
​
object
Environment variables set for this process only.
​
object
Allocate a pseudo-terminal for this process. Required for interactive programs such as shells, editors, and TUI applications.
Response — 201 Created
​
integer
required
The process ID inside the sandbox. Use this to stream output, read logs, and send signals.
​
string
required
The command as started.
​
string
required
ISO 8601 timestamp when the process was spawned.
​
boolean
required
True if the process is still running at the time of this response.
​
boolean
required
True if a pseudo-terminal was allocated.
Error codes: 400 malformed request · 401 unauthenticated · 429 concurrent-connection cap reached

​
GET /processes

Lists the processes the agent supervises inside the sandbox. This includes running processes and recently exited ones that the agent has not yet reaped.
Response — 200 OK
​
Process[]
required
Array of process objects. Each has the same fields as the POST /processes response: pid, command, started_at, running, pty, exit_code (when exited), and exited_at (when exited).
Error codes: 401 unauthenticated

​
GET /processes/

Gets the current state of a single supervised process.
Path parameters
​
integer
required
The process ID as returned by POST /processes.
Response — 200 OK
​
integer
required
Process ID.
​
string
required
The command that was started.
​
string
required
ISO 8601 start timestamp.
​
boolean
required
True if the process is still running.
​
boolean
required
True if a PTY was allocated.
​
integer
Exit code, present when the process has exited. Negative values indicate the process was killed by a signal.
​
string
ISO 8601 timestamp when the process exited.
Error codes: 401 unauthenticated · 404 process not found

​
DELETE /processes/

Sends a Unix signal to a supervised process. The default is SIGTERM. Use SIGKILL when the process does not respond to SIGTERM.
Path parameters
​
integer
required
The process ID.
Query parameters
​
string
The signal to deliver. One of SIGTERM (default), SIGKILL, SIGINT, or SIGHUP.
Response — 204 No Content Error codes: 401 unauthenticated · 404 process not found

​
GET /processes//logs

Reads buffered output that the agent has retained for this process. The agent keeps a ring buffer of recent output; use the after parameter to read new chunks since your last call. For live output, use the WebSocket stream instead.
Path parameters
​
integer
required
The process ID.
Query parameters
​
integer
Return output chunks with a sequence number greater than this value. Default 0 to read from the beginning of the retained buffer.
Response — 200 OK
​
object[]
required
Log chunks in sequence order.
​
integer
required
The next sequence number. Pass as after on the next call.
​
boolean
required
True if the process is still running at the time of this response.
​
integer
Exit code, present when running is false.
​
integer
The lowest sequence number currently retained. If this is greater than your last after value, some output has been evicted from the ring buffer.
Error codes: 401 unauthenticated · 404 process not found