Sign Up
Docs v2.0

Processes

List processes

GET
/processes

List process records, optionally filtered by state, kind, session, name, or pid.

Query Parameters

state?string

running, terminal, or all (the default when omitted).

kind?string

Filter by process kind.

Value in"exec""pty""code"
sessionId?string

Filter by session id.

name?string

Filter by live name alias.

pid?integer

Filter by OS process id.

Formatint32

Response Body

application/json
  1. response

GET /processes response body.

items*array<>

Matching processes in creation order.

curl -X GET 'http://sandbox:2280/processes'
{  "items": [    {      "argv": [        "string"      ],      "code": "string",      "createdAt": "string",      "cwd": "string",      "exitCode": 0,      "exitedAt": "string",      "id": "string",      "keepLogs": "until_cleanup",      "kind": "exec",      "language": "string",      "login": true,      "name": "string",      "pid": 0,      "reason": null,      "resolvedShell": "string",      "sessionId": "string",      "shell": "string",      "shellCommand": "string",      "signal": "string",      "startedAt": "string",      "state": "starting",      "stdin": "closed",      "system": true,      "terminal": null,      "timeoutMs": 0,      "user": "string",      "firstAvailableCursor": "string",      "lastCursor": "string",      "logs": null,      "truncatedHead": true    }  ]}

Create a process

POST
/processes

Create a process record and launch exec, pty, or code work. waitMs keeps the request open until terminal or timeout; logs=text|base64 adds the first log page and therefore requires waitMs.

Query Parameters

waitMs?integer

Wait up to this many milliseconds before replying; timing out still returns 201 with a running record.

Formatint64
Range0 <= value
logs?string

Inline the first logs page using text or base64; requires waitMs.

Request Body

application/json
  1. body

POST /processes request body.

argv?array<string>|

argv mode. Exactly one of argv, shellCommand, or code may be present.

code?|

Code to execute through a language-kernel session.

cwd?|

Optional working directory. Empty falls back to the configured default OS user's home for exec/pty processes that run as that user and whose home exists; kind=code, an explicit per-request user, and a missing home fall back to the daemon work dir.

env?

Environment overrides applied at spawn time.

keepLogs?null|
kind?null|
language?|

Code language such as python, typescript, or javascript.

login?boolean

Whether to request a login shell.

name?|

Optional live-only alias. Must be a safe identifier.

sessionId?|

Optional owning session id.

shell?|

Requested shell path or shell name.

shellCommand?|

Shell-command mode. The daemon writes this to a script file before execution.

stdin?null|
terminal?null|
timeoutMs?|

Per-process timeout in milliseconds.

Formatint64
Range0 <= value
user?|

Optional user to run as. Rejected with 400 UNSUPPORTED_OPERATION for kind=code (the language kernel does not run as a sandbox user in v1).

Response Body

Created process record. When waitMs and logs are requested, the response includes the inline logs page.

application/json
  1. response

The process DTO returned by create/get/list.

argv?array<string>|

argv create shape, omitted unless this process was created that way.

code?|

Code source, omitted unless this is a kind=code process.

createdAt*string

RFC 3339 creation timestamp.

cwd*string

Working directory the daemon used.

exitCode?|

Exit code, omitted until terminal.

Formatint32
exitedAt?|

RFC 3339 exit timestamp, omitted until terminal.

id*string

Stable process id.

keepLogs*KeepLogs

Record/log retention policy.

Value in"until_cleanup""on_exit_ttl""none"
kind*Kind

Process kind.

Value in"exec""pty""code"
language?|

Code language, omitted when not applicable.

login?boolean

Whether the daemon requested a login shell.

name?|

Optional live-only alias, omitted when unnamed.

pid?|

OS process id while running, omitted before spawn and after exit.

Formatint32
reason?null|
resolvedShell?|

Resolved shell path or name, omitted until resolution has happened.

sessionId?|

Owning session id, omitted for standalone processes.

shell?|

Requested shell, omitted when the daemon used its default resolution.

shellCommand?|

Shell command source, omitted unless this process was created that way.

signal?|

Signal name, omitted when none applies.

startedAt?|

RFC 3339 process-start timestamp, omitted until the process starts.

state*State

Lifecycle state.

Value in"starting""provisioning""running""terminal"
stdin*StdinMode

Whether stdin is open.

Value in"closed""open"
system?boolean

Whether this is a protected daemon-owned system process.

terminal?null|
timeoutMs?|

Process timeout in milliseconds, omitted when unset.

Formatint64
Range0 <= value
user?|

Requested user, omitted when the daemon runs as its default user.

firstAvailableCursor?|

Cursor of the first surviving log frame, omitted when nothing was evicted.

lastCursor?|

Cursor of the last known log frame, omitted until at least one frame exists.

logs?null|
truncatedHead*boolean

Whether retention evicted the head of the ledger.

curl -X POST 'http://sandbox:2280/processes' \  -H 'Content-Type: application/json' \  -d '{}'
{  "argv": [    "string"  ],  "code": "string",  "createdAt": "string",  "cwd": "string",  "exitCode": 0,  "exitedAt": "string",  "id": "string",  "keepLogs": "until_cleanup",  "kind": "exec",  "language": "string",  "login": true,  "name": "string",  "pid": 0,  "reason": null,  "resolvedShell": "string",  "sessionId": "string",  "shell": "string",  "shellCommand": "string",  "signal": "string",  "startedAt": "string",  "state": "starting",  "stdin": "closed",  "system": true,  "terminal": null,  "timeoutMs": 0,  "user": "string",  "firstAvailableCursor": "string",  "lastCursor": "string",  "logs": null,  "truncatedHead": true}

Get a process

GET
/processes/{id}

Fetch a process by stable id or by its live alias.

Path Parameters

id*string

Process id or live alias.

Response Body

application/json
  1. response

The process DTO returned by create/get/list.

argv?array<string>|

argv create shape, omitted unless this process was created that way.

code?|

Code source, omitted unless this is a kind=code process.

createdAt*string

RFC 3339 creation timestamp.

cwd*string

Working directory the daemon used.

exitCode?|

Exit code, omitted until terminal.

Formatint32
exitedAt?|

RFC 3339 exit timestamp, omitted until terminal.

id*string

Stable process id.

keepLogs*KeepLogs

Record/log retention policy.

Value in"until_cleanup""on_exit_ttl""none"
kind*Kind

Process kind.

Value in"exec""pty""code"
language?|

Code language, omitted when not applicable.

login?boolean

Whether the daemon requested a login shell.

name?|

Optional live-only alias, omitted when unnamed.

pid?|

OS process id while running, omitted before spawn and after exit.

Formatint32
reason?null|
resolvedShell?|

Resolved shell path or name, omitted until resolution has happened.

sessionId?|

Owning session id, omitted for standalone processes.

shell?|

Requested shell, omitted when the daemon used its default resolution.

shellCommand?|

Shell command source, omitted unless this process was created that way.

signal?|

Signal name, omitted when none applies.

startedAt?|

RFC 3339 process-start timestamp, omitted until the process starts.

state*State

Lifecycle state.

Value in"starting""provisioning""running""terminal"
stdin*StdinMode

Whether stdin is open.

Value in"closed""open"
system?boolean

Whether this is a protected daemon-owned system process.

terminal?null|
timeoutMs?|

Process timeout in milliseconds, omitted when unset.

Formatint64
Range0 <= value
user?|

Requested user, omitted when the daemon runs as its default user.

firstAvailableCursor?|

Cursor of the first surviving log frame, omitted when nothing was evicted.

lastCursor?|

Cursor of the last known log frame, omitted until at least one frame exists.

logs?null|
truncatedHead*boolean

Whether retention evicted the head of the ledger.

curl -X GET 'http://sandbox:2280/processes/string'
{  "argv": [    "string"  ],  "code": "string",  "createdAt": "string",  "cwd": "string",  "exitCode": 0,  "exitedAt": "string",  "id": "string",  "keepLogs": "until_cleanup",  "kind": "exec",  "language": "string",  "login": true,  "name": "string",  "pid": 0,  "reason": null,  "resolvedShell": "string",  "sessionId": "string",  "shell": "string",  "shellCommand": "string",  "signal": "string",  "startedAt": "string",  "state": "starting",  "stdin": "closed",  "system": true,  "terminal": null,  "timeoutMs": 0,  "user": "string",  "firstAvailableCursor": "string",  "lastCursor": "string",  "logs": null,  "truncatedHead": true}

Delete a process record

DELETE
/processes/{id}

Delete a process record and purge its logs. System processes stay protected.

Path Parameters

id*string

Process id or live alias.

Response Body

Process record deleted.

curl -X DELETE 'http://sandbox:2280/processes/string'
Empty

Attach a websocket to a process

GET
/processes/{id}/attach

Upgrades to a websocket that streams live output frames and accepts stdin bytes. When cursor is set, the daemon replays ledger bytes up to the attach-time tail first. Invalid or expired replay cursors are reported as websocket policy closes (1008), not HTTP errors.

Path Parameters

id*string

Process id or live alias.

Query Parameters

cursor?string

Optional logs cursor to replay before switching to live websocket output.

Response Body

Websocket upgrade accepted.

curl -X GET 'http://sandbox:2280/processes/string/attach'
Empty

Read process logs or follow them as SSE

GET
/processes/{id}/logs

Returns a JSON page by default, or an SSE stream when follow=true. SSE event names are log, state, warning, error, and eof; Last-Event-ID resumes from the last seen cursor.

Path Parameters

id*string

Process id or live alias.

Query Parameters

cursor?string

Resume after this cursor. Empty or omitted starts from the beginning.

limit?integer

Page size for JSON reads; clamped by the daemon.

Range0 <= value
encoding?string

Payload encoding: text (default) or base64.

follow?boolean

When true, answer an SSE follow stream instead of a JSON page.

Header Parameters

Last-Event-ID?|

Optional resume cursor for SSE reconnects; wins over the cursor query parameter.

Response Body

SSE stream when follow=true: log carries LogFrameDto, state carries ProcessStateEventDto, warning carries ProcessWarningEventDto, error carries ProcessErrorEventDto, and eof carries ProcessEofEventDto.

text/event-stream
curl -X GET 'http://sandbox:2280/processes/string/logs'
Empty

Resize a PTY

POST
/processes/{id}/resize

Change the terminal size of a PTY process.

Path Parameters

id*string

Process id or live alias.

Request Body

application/json
  1. body

POST /processes/{id}/resize body.

cols*integer

PTY columns; must be at least 1.

Formatint32
Range1 <= value
rows*integer

PTY rows; must be at least 1.

Formatint32
Range1 <= value

Response Body

PTY resized.

curl -X POST 'http://sandbox:2280/processes/string/resize' \  -H 'Content-Type: application/json' \  -d '{  "cols": 1,  "rows": 1}'
Empty

Signal a process

POST
/processes/{id}/signals

Send a signal, optionally with escalation, or interrupt a running code execution.

Path Parameters

id*string

Process id or live alias.

Request Body

application/json
  1. body

POST /processes/{id}/signals body.

escalateAfterMs?|

Grace period in milliseconds before escalating. Maximum 600000.

Formatint64
Range0 <= value
escalateTo?|

Escalation signal name. Defaults to SIGKILL when omitted.

signal?string

Signal name such as SIGTERM, SIGKILL, or SIGINT. Empty means SIGTERM.

Response Body

Signal accepted.

curl -X POST 'http://sandbox:2280/processes/string/signals' \  -H 'Content-Type: application/json' \  -d '{}'
Empty

Write process stdin

POST
/processes/{id}/stdin

Write stdin data and optionally close stdin.

Path Parameters

id*string

Process id or live alias.

Request Body

application/json
  1. body

POST /processes/{id}/stdin body.

data?string

Data to write. Text by default, or base64url when encoding=base64.

encoding?|

Optional payload encoding: text (default) or base64.

eof?boolean

Whether this request also closes stdin after writing.

Response Body

stdin written.

curl -X POST 'http://sandbox:2280/processes/string/stdin' \  -H 'Content-Type: application/json' \  -d '{}'
Empty

Wait for process completion

GET
/processes/{id}/wait

Long-poll for the terminal result. Omitted timeoutMs keeps the daemon's default 60-second chunk, timeoutMs=0 waits until terminal, and any positive value is honored uncapped. Timing out returns reason: timed_out without killing the process.

Path Parameters

id*string

Process id or live alias.

Query Parameters

timeoutMs?integer

Long-poll timeout in milliseconds. Omitted means the daemon's default 60-second chunk; 0 means wait until terminal; any positive value is honored uncapped.

Formatint64
Range0 <= value

Response Body

application/json
  1. response

Terminal result returned by GET /processes/{id}/wait and SSE state events.

exitCode?|

Process exit code, when the platform has one.

Formatint32
reason?null|
signal?|

Signal name such as SIGKILL, omitted when none applies.

curl -X GET 'http://sandbox:2280/processes/string/wait'
{  "exitCode": 0,  "reason": null,  "signal": "string"}

Computersfor Agents

Isolated sandboxes for agent code,
ready in under 100 ms.

Start for Free