Skip to main content

Run a command

Use executions when an agent or backend needs to run a command without opening SSH. Execution is asynchronous: create returns immediately, you poll until , then fetch output.

Create

Start an execution. Returns immediately.
string
required
The machine to run the command on.
string[]
required
argv array. The first element is the executable; the rest are arguments.
string
Bytes to pipe to the process’s stdin.
object
Extra environment variables for this process.
string
default:"/root"
Working directory.
integer
Hard kill after this many milliseconds.

Retrieve

Get the current state of an execution. Use this to poll until terminal.
string
required
The machine that owns the execution.
string
required
The execution to retrieve.

List

List executions on a machine, newest first.
string
required
The machine whose executions you want to list.
string
Pagination cursor from a prior page’s next_cursor.
integer
Max items per page.

Delete

Cancel a running execution. No-op if already terminated.
string
required
The machine that owns the execution.
string
required
The execution to cancel.

Events

Per-execution event log: stdout/stderr chunks plus lifecycle transitions. Cursor-paginated.
string
required
The machine that owns the execution.
string
required
The execution whose events you want to read.
string
Pagination cursor from a prior page’s next_cursor.
integer
Max events per page.

Output

Output returns the command’s captured stdout and stderr after the execution finishes.
string
required
The machine that owns the execution.
string
required
The finished execution whose output you want.
Last modified on June 30, 2026