Sign Up

Processes

List processes

GET
/processes

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

Query Parameters

state?string

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

kind?string

Filter by process kind.

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

Filter by the session a process ran in (kind=session process id or interpreter context id).

name?string

Filter by live name alias.

pid?integer

Filter by OS process id.

Formatint32
tag?string

Filter by tag.

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,      "tag": "string",      "terminal": null,      "timeoutMs": 0,      "user": "string",      "firstAvailableCursor": "string",      "lastCursor": "string",      "logs": null,      "truncatedHead": true    }  ]}

Create a process

POST
/processes

Launch an exec, PTY, or code process. waitMs waits for completion or timeout; logs=text|base64 includes the first log page and 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. base64 uses the standard RFC 4648 section 4 alphabet (+/) with = padding.

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 in an interpreter session.

cwd?|

Optional working directory. For exec and pty, defaults to the configured user’s home when available. Code execution, an explicit user, or an unavailable home uses the sandbox’s default working directory.

env?

Environment overrides applied at spawn time. PTY processes default to TERM=xterm-256color; an explicit TERM overrides the default.

keepLogs?null|
kind?null|
language?|

Code language, exactly python, typescript or javascript (case-sensitive). Unknown values, including an empty string, answer 400 UNSUPPORTED_OPERATION before provisioning. Omit when using an explicit session's language; without sessionId, omission answers 400 BAD_REQUEST.

login?boolean

Whether to request a login shell.

name?|

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

sessionId?|

The session to run in. For kind=exec: the id or live name of a kind=session process; the shellCommand runs inside its shell, one command at a time, in order, and the request refuses argv, cwd, env, shell, login: true, user and tag (the session's settings apply; the command takes the session's tag). Unknown ids answer SESSION_NOT_FOUND (sessions are never created on first use) and an ended or deleted session answers SESSION_ENDED. For kind=code: the interpreter context to execute in.

shell?|

Requested shell path or shell name. For kind=session on Linux and macOS it must be a POSIX shell (bash, sh, dash, zsh, ksh): the session answers 400 PROCESS_START_FAILED when the shell does not run POSIX commands within 5 s of starting.

shellCommand?|

Shell command to execute.

stdin?null|
tag?|

Optional tag, a safe identifier ([A-Za-z0-9._-], 1-128 characters, not . or ..) that groups this process with others for GET /processes?tag= and POST /processes:kill. Applies to kind=exec, pty and session. kind=code refuses it, and so does a command run in a session, which takes the session's tag.

terminal?null|
timeoutMs?|

Per-process execution timeout in milliseconds. Omitted or 0 means no limit. Positive timeouts apply to exec and PTY processes (including exec commands in a shell session); code executions and shell-session creation refuse positive timeouts. For a session command, the timeout starts when execution begins, excluding time queued behind earlier commands. On expiry the command is stopped if possible. If it has not stopped after a further 5 seconds, the session and its background processes are ended.

Formatint64
Range0 <= value
user?|

Optional execution user. Not supported for kind=code; returns 400 UNSUPPORTED_OPERATION.

Response Body

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

application/json
  1. response

Process information returned by create, get, and list operations.

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 API used. For a kind=session process, the session shell's current directory, updated after each command; for a command run in a session, the shell's directory when the command started.

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""session"
language?|

Code language, omitted when not applicable.

login?boolean

Whether the API requested a login shell.

name?|

Optional live-only alias, omitted when unnamed.

pid?|

OS process id while running, omitted before spawn and after exit. Always omitted for commands run in a session: they run inside the session's shell, whose own record carries its pid.

Formatint32
reason?null|
resolvedShell?|

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

sessionId?|

The session this process ran in: a kind=session process for shell commands, or the interpreter context for kind=code. Omitted for standalone processes.

shell?|

Requested shell, omitted when the API 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 system process.

tag?|

The tag the process was created with, omitted when it has none. A command run in a session carries the session's tag. Never changes.

terminal?null|
timeoutMs?|

Process execution timeout in milliseconds; omitted or 0 means no limit.

Formatint64
Range0 <= value
user?|

Requested user, omitted when the API 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 removed earlier output logs.

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,  "tag": "string",  "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

Process information returned by create, get, and list operations.

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 API used. For a kind=session process, the session shell's current directory, updated after each command; for a command run in a session, the shell's directory when the command started.

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""session"
language?|

Code language, omitted when not applicable.

login?boolean

Whether the API requested a login shell.

name?|

Optional live-only alias, omitted when unnamed.

pid?|

OS process id while running, omitted before spawn and after exit. Always omitted for commands run in a session: they run inside the session's shell, whose own record carries its pid.

Formatint32
reason?null|
resolvedShell?|

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

sessionId?|

The session this process ran in: a kind=session process for shell commands, or the interpreter context for kind=code. Omitted for standalone processes.

shell?|

Requested shell, omitted when the API 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 system process.

tag?|

The tag the process was created with, omitted when it has none. A command run in a session carries the session's tag. Never changes.

terminal?null|
timeoutMs?|

Process execution timeout in milliseconds; omitted or 0 means no limit.

Formatint64
Range0 <= value
user?|

Requested user, omitted when the API 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 removed earlier output logs.

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,  "tag": "string",  "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

Open a WebSocket for live output and stdin. Clients that cannot send an Authorization header may send the sandbox access token in the daytona_token query parameter. With cursor, available logs through the connection time are replayed before live output. Invalid or expired cursors cause WebSocket policy close 1008, not an HTTP error.

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 API.

Range0 <= value
encoding?string

Payload encoding: text (default) or base64. base64 uses the standard RFC 4648 section 4 alphabet (+/) with = padding, including SSE follow frames.

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

JSON log page (application/json) when follow is absent or false; SSE stream (text/event-stream) when follow=true: log carries LogFrameDto, state carries ProcessStateEventDto, warning carries ProcessWarningEventDto, error carries ProcessErrorEventDto, and eof carries ProcessEofEventDto.

  1. response

JSON page body from GET /processes/{id}/logs.

eof*boolean

Whether the process is terminal and there are no more frames after this page.

firstAvailableCursor?|

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

frames*array<>

Frames in this page.

nextCursor*string

Cursor the client should pass to continue from the end of this page.

truncatedHead*boolean

Whether retention evicted older frames before this page.

curl -X GET 'http://sandbox:2280/processes/string/logs'
{  "eof": true,  "firstAvailableCursor": "string",  "frames": [    {      "channel": "string",      "cursor": "string",      "data": "string",      "timestamp": 0    }  ],  "nextCursor": "string",  "truncatedHead": true}

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; an integer in 1..=65535. Windows: at most 32767.

Formatint32
Range1 <= value <= 65535
rows*integer

PTY rows; an integer in 1..=65535. Windows: at most 32767.

Formatint32
Range1 <= value <= 65535

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. On a Linux sandbox with process containment, SIGTERM and SIGKILL reach every process the target started, also after the target itself exited: such a request answers PROCESS_TERMINAL only once nothing it started is running.

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. With encoding=base64, accepts standard RFC 4648 section 4 base64 (+/) or base64url (-_), padded or unpadded.

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 API'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 API'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"}

Kill every process with a tag

POST
/processes:kill

Kill every process created with tag, and everything those processes started, including descendants that detached and the survivors of tagged processes that already exited. Returns only when none of them is running. Records and logs are kept. The tag can be used again right after the call.

Request Body

application/json
  1. body

POST /processes:kill request body.

tag*string

The tag whose processes to kill: a safe identifier ([A-Za-z0-9._-], 1-128 characters, not . or ..).

timeoutMs?|

How long to wait for every killed process to exit, in milliseconds. 1-60000; default 10000.

Formatint64
Range1 <= value <= 60000

Response Body

Every process created under the tag before the call, and everything it started, has exited. A start admitted after the call may be running.

application/json
  1. response

POST /processes:kill response body.

processIds*array<string>

The tagged processes that were still running when the call started, and exited tagged processes that still had descendants running. Every one of them, and everything it started, has exited. Processes whose records were deleted or expired are killed too but not listed, so an empty list does not mean nothing was stopped.

curl -X POST 'http://sandbox:2280/processes:kill' \  -H 'Content-Type: application/json' \  -d '{  "tag": "string"}'
{  "processIds": [    "string"  ]}

Computersfor Agents

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

Start for Free