> ## Documentation Index > Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run a command and stream output over SSE > Runs a command and streams its output as Server-Sent Events while it runs. Each `data:` line is a JSON object: an output chunk (`{"stdout":"..."}` or `{"stderr":"..."}`), the terminal event (`{"exit_code":N,"finished":true}`), or an error (`{"error":"...","finished":true}`). The stream closes when the command exits. The sandbox must be `running`; a paused sandbox returns `503`. Activate it first with `POST /sandboxes/{sandbox_id}/activate` (the SDKs do this automatically). `timeout_s` is a hard runtime limit: the command is killed after that many seconds regardless of output, exiting with code 124. ## OpenAPI ````yaml https://raw.githubusercontent.com/superserve-ai/sandbox/refs/heads/main/api/openapi.yaml post /exec/stream openapi: 3.1.0 info: title: Superserve API version: 0.1.0 description: > Superserve provides sandbox infrastructure to run AI agents in the cloud. Powered by Firecracker MicroVMs. ## Sandbox lifecycle ``` active <--> paused --> deleted ``` A sandbox is `active` when running and `paused` after being paused. Resuming a paused sandbox returns it to `active`. Deleting releases all resources. | Endpoint | What it does | |----------|-------------| | `POST /sandboxes` | Create a new sandbox (optionally `from_template`) | | `PATCH /sandboxes/:id` | Partially update a running sandbox (e.g. network rules) | | `POST /sandboxes/:id/pause` | Snapshot full state, suspend the VM | | `POST /sandboxes/:id/resume` | Restore from snapshot, continue where it left off | | `DELETE /sandboxes/:id` | Delete sandbox and all resources | ## Sandbox environment By default sandboxes boot from the curated `superserve/base` template (Ubuntu 24.04, 1 vCPU, 1 GB RAM, 4 GB disk, with Python 3.12, Node.js 22, npm, git, curl, and build-essential pre-installed). Callers can override with any template name (e.g. `superserve/python-3.11`, `superserve/node-22`) or a team-owned template UUID via the `from_template` field on `POST /sandboxes`. ## Files and commands `/files`, `/exec`, and `/exec/stream` run against a single sandbox and use its `X-Access-Token` (returned by create, resume, and activate), not the team API key. Two host forms reach them: - `https://sandbox.superserve.ai/...` with `X-Superserve-Sandbox-Id: `. - `https://boxd-{sandbox_id}.sandbox.superserve.ai/...` — no routing header needed. contact: name: Superserve Team license: name: Proprietary servers: - url: https://api.superserve.ai description: Production security: [] paths: /exec/stream: servers: - url: https://sandbox.superserve.ai description: Shared host — send the sandbox ID in `X-Superserve-Sandbox-Id`. - url: https://boxd-{sandbox_id}.sandbox.superserve.ai description: Per-sandbox host. variables: sandbox_id: default: '' description: The sandbox ID. post: tags: - Exec summary: Run a command and stream output over SSE description: | Runs a command and streams its output as Server-Sent Events while it runs. Each `data:` line is a JSON object: an output chunk (`{"stdout":"..."}` or `{"stderr":"..."}`), the terminal event (`{"exit_code":N,"finished":true}`), or an error (`{"error":"...","finished":true}`). The stream closes when the command exits. The sandbox must be `running`; a paused sandbox returns `503`. Activate it first with `POST /sandboxes/{sandbox_id}/activate` (the SDKs do this automatically). `timeout_s` is a hard runtime limit: the command is killed after that many seconds regardless of output, exiting with code 124. operationId: execStream requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExecRequest' responses: '200': description: A Server-Sent Events stream of output and lifecycle events. content: text/event-stream: schema: $ref: '#/components/schemas/ExecStreamEvent' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - accessToken: [] components: schemas: ExecRequest: type: object required: - command properties: command: type: string minLength: 1 description: >- Command to execute. Wrapped in `/bin/sh -c` unless `args` is provided. args: type: array items: type: string description: >- If provided, `command` is used as the binary and `args` as arguments (no shell wrapping). env: type: object additionalProperties: type: string description: Environment variables for the command. working_dir: type: string description: Working directory (default `/home/user`). timeout_s: type: integer default: 30 description: Timeout in seconds. ExecStreamEvent: type: object description: > One Server-Sent Event from `POST /exec/stream`, delivered as a `data:` line carrying this JSON object. Output events carry `stdout` or `stderr` (each with a `timestamp`); the terminal event carries `finished: true` with `exit_code`, or `error` and `code` if the command could not be run. The stream may also include SSE comment keepalive lines (`: keepalive`), which carry no data. properties: timestamp: type: string format: date-time description: RFC 3339 time the event was emitted (output and terminal events). stdout: type: string description: A chunk of standard output. stderr: type: string description: A chunk of standard error. finished: type: boolean description: Present and `true` on the terminal event. exit_code: type: integer description: Process exit code, on the terminal event. error: type: string description: Error message if the command could not be run. code: type: string description: Error code accompanying `error` (e.g. `bad_request`, `exec_failed`). Error: type: object description: | Error envelope. `error.code` is a stable, machine-readable identifier (e.g. `bad_request`, `not_found`, `conflict`, `rate_limited`, `too_many_builds`, `too_many_templates`, `too_many_sandboxes`, `image_pull_failed`, `step_failed`, `snapshot_failed`, `start_cmd_failed`, `ready_cmd_failed`, `build_failed`). `error.message` is human-readable and may change between releases; clients should branch on `code`, not `message`. properties: error: type: object properties: code: type: string message: type: string responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: > The sandbox is not currently running (for example, paused) or is temporarily unavailable. For a paused sandbox, activate it with `POST /sandboxes/{sandbox_id}/activate` and retry; the SDKs do this automatically. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: accessToken: type: apiKey in: header name: X-Access-Token description: > Per-sandbox token returned by create, resume, and activate. Grants access to a single sandbox's files and commands. Distinct from the team `X-API-Key`. ````