Execs

GET/v1/execs/{id}

Auth: API key

One exec by id alone, without knowing its sandbox or run. An exec belonging to another org is a 404, never a 403. A background command's id (x_…) answers as GET /v1/sandboxes/:id/execs/:exec_id does, with the same ?stream, ?offset, ?len and ?wait_ms; after a restart of the service that id is found only through its sandbox.

Parameters

idrequiredpath · string

lenquery · integer

offsetquery · integer

streamquery · string

untilquery · string

wait_msquery · integer

Answer 200 · ExecView · application/json

argvrequiredstring[]

The command, as it was run.

cpu_msrequirednumber

cwdstring | null

The working directory it ran in.

env_keysrequiredstring[]

The names of the environment variables it was given. Never the values.

exec_idrequiredstring

exit_codeinteger | null

null while it is still running, or if a signal killed it.

max_rss_kibrequiredinteger

Peak resident memory, in kibibytes.

run_idrequiredstring

sandbox_idrequiredstring

signalinteger | null

The signal that killed it, if one did.

started_atrequiredstring

When it started, RFC 3339.

stderrrequiredstring

stdoutrequiredstring

terminalrequiredboolean

True when this command owned the sandbox: the sandbox ends when the command does.

truncatedrequiredboolean

True when the output was cut: at the request's byte limit, or, in a sandbox's execs, to the last 64 KiB of each stream. GET /v1/execs/{id} returns the whole recorded output.

wall_msrequirednumber

GET/v1/sandboxes/{id}/execs

Auth: API key

List this sandbox's background execs.

Parameters

idrequiredpath · string

Answer 200 · BackgroundExecList · application/json

execsrequiredBackgroundExec[]

sandbox_idrequiredstring

POST/v1/sandboxes/{id}/execs

Auth: API key

Run a command. Buffered by default; Accept: text/event-stream streams it; background: true returns 202 with a handle instead of waiting. A sandbox parked by its auto_pause_s rule is woken first; one paused with POST …/pause is not, and answers that it is paused. max_output_bytes (default 64 KiB) is per stream and at most 32 MiB; output past it is cut and the reply says truncated: true.

Parameters

idrequiredpath · string

Idempotency-Keyheader · string

Optional. Makes a retried command safe: send the same key on every attempt of ONE command and it runs once. Kept 24 hours per org. The same key with the same request answers with the first answer (same exec_id), marked Idempotent-Replayed: true; the same key with a different request is refused with 409 idempotency_key_reused. Honoured on a buffered or background command; a streamed one (Accept: text/event-stream) refuses a key. At most 1 MiB of output is kept for a replay: a replay of a longer answer is cut and says so with replay_truncated: true. Nothing is kept unless you send a key; the SDKs send one only when you pass it.

Request body ExecCreate · application/json · optional

argvstring[] | null

The program and its arguments, run without a shell.

backgroundboolean

Answer at once (202) with a handle to poll, instead of waiting for the command.

cwdstring | null

The working directory. Defaults to the snapshot's workspace.

encodingstring | null

text (the default) or base64: the answer's output as stdout_b64 / stderr_b64, the exact bytes, for output that is not text (an archive, an image). The buffered answer only.

envmap of string

Extra environment variables.

followboolean

With background: the command is read as it runs, by a caller that may lose its connection and come back. The newest max_output_bytes of each stream are kept (8 MiB by default; older bytes are dropped, and a read that asks for them says how many in skipped), and the handle is freed 10 minutes after the command ends, read or not. The command never stops because a caller went away.

kill_on_exitboolean | null

End the sandbox when the command exits (default: the value of terminal).

max_output_bytesinteger | null

Output kept per stream, in bytes (default 64 KiB, 1 MiB for a background exec; max 32 MiB).

secretsSecretUse[]

Stored secrets the command receives as environment variables.

shstring | null

A line for sh -c.

stdinboolean

Keep the command's stdin open for POST …/execs/{exec_id}/stdin (background execs).

terminalboolean

The sandbox ends when this command exits.

timeout_msinteger | null

Milliseconds before the command is ended. A positive integer; omitted, 15 minutes.

userstring | null

The user to run as.

Answer 200 · ExecResult · application/json

cpu_msnumber | null

exec_idrequiredstring

exit_codeinteger | null

null if a signal killed the command.

oom_killedboolean

Present (true) when the command was killed for running out of memory.

reasonstring | null

Why the command ended without an exit code: timeout, out_of_memory or signal. Absent when it exited on its own.

sandbox_idrequiredstring

signalinteger | null

The signal that killed it, if one did.

stderrstring | null

stderr_b64string | null

With encoding: "base64": the exact bytes of standard error, base64.

stdoutstring | null

stdout_b64string | null

With encoding: "base64": the exact bytes of standard output, base64 (stdout is then empty). Bytes that are not UTF-8 survive here; as text they become U+FFFD.

timed_outboolean

Present (true) when the command was killed at its own timeout_ms.

truncatedrequiredboolean

True when the output was cut at the request's byte limit.

wall_msnumber | null

GET/v1/sandboxes/{id}/execs/{exec_id}

Auth: API key

Read a background exec. ?stream=stdout|stderr&offset=&len= takes a byte range; ?wait_ms=N parks until it exits.

Parameters

idrequiredpath · string

exec_idrequiredpath · string

lenquery · integer

offsetquery · integer

streamquery · string

untilquery · string

wait_msquery · integer

Answer 200 · BackgroundExec · application/json

argvstring | null

The command, as one line.

backgroundrequiredboolean

Always true: this is the handle form of a command.

datastring | null

The bytes, base64.

eofboolean | null

True when data reaches the end of what is held so far.

errorBackgroundExecError | null

Why the command could not run; only when state is failed.

exec_idrequiredstring

exitBackgroundExecExit | null

How the command ended; only once state is exited.

followboolean | null

Started with follow: the newest output is kept, and the handle is freed 10 minutes after the command ends.

idle_hold_sinteger | null

Present when the sandbox pauses itself when idle: after this command ends, the idle rule waits up to this many seconds for its result to be read before it pauses the sandbox (a pause drops the handle and its output). Reading its output once it has finished releases the hold, and so does deleting the handle (DELETE /v1/sandboxes/{id}/execs/{exec_id}, CLI exec kill EXEC --forget).

idle_hold_untilstring | null

When this finished command stops holding the idle rule off (RFC 3339), while it still does: absent for a running command, once its output has been read, and once the time has passed.

leninteger | null

Bytes in data.

offsetinteger | null

sandbox_idrequiredstring

skippedinteger | null

A follow command only: bytes between the offset asked for and the first byte still held, dropped to keep the newest output; data then starts at offset + skipped.

started_unix_nsinteger | null

Unix nanoseconds.

staterequiredstring

running | exited | failed.

stderr_bytesinteger | null

stderr_totalinteger | null

stdin_openboolean | null

True while the command's standard input can still be written to.

stdout_bytesinteger | null

Bytes of standard output held and readable by range.

stdout_totalinteger | null

Bytes of standard output the command has written in total.

streaminteger | null

Which stream data is from: 1 for stdout, 2 for stderr.

truncatedboolean | null

True when more was written than is held.

waited_msinteger | null

How long a ?wait_ms= read waited, in milliseconds.

DELETE/v1/sandboxes/{id}/execs/{exec_id}

Auth: API key

SIGKILL the background exec and drop its handle and buffered output.

Parameters

idrequiredpath · string

exec_idrequiredpath · string

Answer 200 · ExecForgotten · application/json

exec_idrequiredstring

forgottenrequiredboolean

okrequiredboolean

sandbox_idrequiredstring

POST/v1/sandboxes/{id}/execs/{exec_id}/signal

Auth: API key

Signal a background exec.

Parameters

idrequiredpath · string

exec_idrequiredpath · string

Request body ExecSignal · application/json · optional

signalNumberOrName | null

A signal number 1–64, or a name such as SIGTERM or TERM. Default 15 (SIGTERM).

Answer 200 · ExecSignalled · application/json

already_endedboolean | null

Present, and true, only when the command had already finished.

deliveredrequiredboolean

False when the command had already finished, which is not a failure: the process is gone, which is what a kill wanted.

exec_idrequiredstring

okrequiredboolean

sandbox_idrequiredstring

signalrequiredinteger

The signal that was sent, as a number.

POST/v1/sandboxes/{id}/execs/{exec_id}/stdin

Auth: API key

Write to a running command's standard input, and close it. data is base64 — stdin is bytes, and a JSON string cannot carry all of them. Send data and eof together for the common "write this and close". The command must have been started with stdin: true; a process already running on /dev/null cannot be handed an input later, so writing to one is an error rather than a write that goes nowhere.

Parameters

idrequiredpath · string

exec_idrequiredpath · string

Request body ExecStdin · application/json · optional

datastring | null

Bytes to write, base64.

eofboolean

Close stdin after this write.

Answer 200 · StdinAck · application/json

eofrequiredboolean

This call closed the input side.

exec_idrequiredstring

okrequiredboolean

sandbox_idrequiredstring

writtenrequiredinteger

Bytes handed to the child's stdin by this call.