Exec Runs API

Dispatch commands to a connected remote and read their output. Each exec run is a stored record. Output is stored separately as sequenced chunks.

Requires API key scopes remotes:read (list, get, read output) and remotes:write (dispatch, signal). Create keys in settings → workspace → api keys.

→ Remotes API · Remotes guide

Overview

An exec run is one command executed on a remote. The API creates the run, asks the remote daemon to start the process over the WebSocket, and stores stdout/stderr as sequenced chunks.

The remote must be connected and have exec_enabled: true (start it with belt remote start --exec).

While a run is in progress. Dispatch requires a live connection, but a command already running on the host keeps going if the daemon drops the WebSocket briefly. The API fails unfinished exec runs when the remote reaches stopped (about 30 seconds after disconnect), not when it is merely disconnected. Reconnect the daemon within that window to keep long-running commands alive.

Dispatch exec run

POST /remotes/{remote_id}/execs

Starts a command on a remote the caller owns. Requires remotes:write.

Request

1{2  "command": "bash",3  "args": ["-c", "echo hello && uname -a"],4  "cwd": "/home/dev/project",5  "timeout_ms": 600006}

1curl -X POST https://api.inference.sh/remotes/remote_abc123/execs \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{"command":"ls","args":["-la"]}'

Response

Returns an ExecRunDTO. The run is already running when dispatch succeeds.

Errors

Get exec run

GET /execs/{id}

Returns a single exec run. Requires remotes:read.

1curl https://api.inference.sh/execs/exec_abc123 \2  -H "Authorization: Bearer inf_your_key"

Poll this endpoint until status is terminal (exited, killed, or denied).

List exec runs

GET /execs or POST /execs/list

Cursor-paginated list. Requires remotes:read. See REST overview: cursor pagination.

Read output

GET /execs/{id}/output?after_seq={n}

Returns output chunks with seq greater than after_seq, in ascending order. Requires remotes:read.

Each item is an ExecRunOutputDTO:

1{2  "id": "out_abc123",3  "created_at": "2026-01-01T12:00:00Z",4  "exec_run_id": "exec_abc123",5  "seq": 1,6  "stream": "stdout",7  "data": "aGVsbG8K"8}

A request returns at most 2000 chunks.

Resume after disconnect

1. Read last_seq from GET /execs/{id}, or track the highest seq you have processed.
2. Call GET /execs/{id}/output?after_seq={seq} to fetch only newer chunks.
3. Repeat until the run reaches a terminal status.

last_seq only moves forward. A late or duplicate frame with a lower seq does not rewind it.

1# Fetch chunks after sequence 422curl "https://api.inference.sh/execs/exec_abc123/output?after_seq=42" \3  -H "Authorization: Bearer inf_your_key"

Signal (cancel)

POST /execs/{id}/signal

Asks the remote daemon to kill a running exec. Requires remotes:write.

1curl -X POST https://api.inference.sh/execs/exec_abc123/signal \2  -H "Authorization: Bearer inf_your_key"

1{2  "ok": true3}

The response is a bare JSON object without the standard envelope. The call does nothing when the run is already terminal.

Exec run status values

Automatic termination

Some terminal states are applied by the platform when the remote disconnects or you stop the chat:

Valid transitions

Terminal states are final.

CLI equivalent

1# On the remote machine: opt in to command execution2belt remote --exec34# From any authenticated client: run a command and stream output5belt remote exec remote_abc123 -- ls -la6belt remote exec remote_abc123 -- bash -c "echo hi && uname -a"

belt remote exec dispatches via POST /remotes/{id}/execs, polls GET /execs/{id}/output with after_seq, and exits with the remote command's exit code.

Flags: --cwd, --timeout (seconds), --pty. The command is destructive. belt prompts for confirmation unless --yes is set.

Related

→ Remotes API: register hosts, exec_enabled, WebSocket protocol

→ REST overview: authentication, cursor pagination, response format