The processes API lets you launch long-running background commands inside a sandbox and inspect their output — useful for starting dev servers, watchers, or any process that runs beyond a single exec call.

Base path: /api/v1/sandboxes/{id}/processes

Endpoints

Start a Process

POST /api/v1/sandboxes/{id}/processes

Auth

Authorization: Bearer msk_...

Request Body

{
  "cmd": "npm run dev -- --port 3000",
  "cwd": "/workspace",
  "name": "dev-server"
}

Response — 201 Created

{
  "data": {
    "pid": "proc_01hwxyz...",
    "name": "dev-server",
    "cmd": "npm run dev -- --port 3000",
    "cwd": "/workspace",
    "status": "running",
    "started_at": "2026-05-26T10:14:23Z",
    "exited_at": null,
    "exit_code": null
  }
}

List Processes

GET /api/v1/sandboxes/{id}/processes

Response — 200 OK

{
  "data": [
    {
      "pid": "proc_01hwxyz...",
      "name": "dev-server",
      "status": "running",
      "started_at": "2026-05-26T10:14:23Z",
      "exited_at": null,
      "exit_code": null
    }
  ]
}

Get Process Status

GET /api/v1/sandboxes/{id}/processes/{pid}

Response — 200 OK

{
  "data": {
    "pid": "proc_01hwxyz...",
    "name": "dev-server",
    "cmd": "npm run dev -- --port 3000",
    "cwd": "/workspace",
    "status": "exited",
    "started_at": "2026-05-26T10:14:23Z",
    "exited_at": "2026-05-26T10:22:01Z",
    "exit_code": 0
  }
}

Process status values:

Stop a Process

DELETE /api/v1/sandboxes/{id}/processes/{pid}

Sends SIGTERM followed by SIGKILL after a grace period.

Response — 204 No Content

Fetch Logs

GET /api/v1/sandboxes/{id}/processes/{pid}/logs

Returns the last N lines of stdout+stderr.

Query Parameters

Response — 200 OK

{
  "data": {
    "lines": [
      "  > Local:   http://localhost:3000",
      "  > Network: http://0.0.0.0:3000",
      "  ready in 743ms"
    ]
  }
}

Live Log Stream (SSE)

GET /api/v1/sandboxes/{id}/processes/{pid}/stream

Streams stdout+stderr as SSE. Uses text/event-stream — requires Bearer token auth.

id: log_001
event: log
data: {"line":"  ready in 743ms","ts":"2026-05-26T10:14:24Z"}

: heartbeat

Errors

Examples