> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox API

> Isolated runtimes where an agent's code executes — create, execute, files, desktop control, tunnels, inference, secrets and usage, generated from the controller’s OpenAPI and source-backed corrections.

<Warning>
  **Confirm deployment access first.** This reference documents a service contract.
  Check the dated [host report](/api-reference/hosts) and obtain a provisioned URL and
  workspace credentials before running examples. Availability and capacity are separate
  from the presence of a reference page.
</Warning>

A sandbox is an isolated runtime an agent can be trusted with: run commands, read and write
files, drive a desktop, open a tunnel, call an LLM through a key-holding proxy — all inside a
container that dies on schedule.

| | |
| - | - |
| Base URL | `https://api.sandbox.stateset.app` |
| Auth | `Authorization: ApiKey <key>` — use this prefix for API keys; `Bearer` accepts a JWT |
| Spec | `GET /openapi.json` — this tab uses a checked-in export with source-backed corrections; confirm the deployed version |
| Lifetime | Sandboxes expire; extend with [`POST /sandbox/{id}/extend`](/api-reference/sandbox/sandbox-by-extend-create), hard cap 24 h |

## Where to start

<CardGroup cols={2}>
  <Card title="Create and execute" icon="terminal" href="/api-reference/sandbox/sandbox-create-create">
    A sandbox with CPUs, memory, isolation and a timeout — then run commands in it.
  </Card>

  <Card title="The end-to-end guide" icon="route" href="/guides/sandbox-first-runtime">
    Create → execute → files → lifetime → teardown, with the cost-capped session pattern.
  </Card>

  <Card title="Files" icon="folder" href="/api-reference/sandbox/sandbox-by-files-write-create">
    Write, read, list, glob, move, copy, watch — the full toolkit.
  </Card>

  <Card title="Secrets & inference" icon="key" href="/api-reference/sandbox/secrets-create">
    Store provider keys once; the [inference proxy](/api-reference/sandbox/sandbox-by-inference-create) injects them so keys never enter the sandbox.
  </Card>
</CardGroup>

## The surface, by group

| Group | What it covers |
| - | - |
| Create | `create`, from-template, `fork` a running sandbox, `promote` it |
| Lifecycle | status, pause / resume, stop, extend, delete |
| Execute | run a command, list executions, read one, stream its output (SSE) |
| Files | write, read, list, delete, glob, mkdir, move, copy, watch |
| Desktop | screenshot (read and take), screen info, mouse, keyboard — for browser/UI work |
| Tunnels | expose a port with a scoped token (default TTL 1 h) |
| Inference | proxy to Anthropic / OpenAI / Google with org-stored secrets |
| Secrets, API keys, Usage, Webhooks | org administration around the runtimes |

<Note>
  The [Computer Use](/api-reference/computer-use/overview) engine drives full jobs against real
  tools; the Sandbox is the lower-level runtime — the place an agent's own code and desktop
  actions execute in isolation. Computer Use runs on sandboxes; you can too.
</Note>

## Related

* [Sandboxes](/stateset-sandbox/stateset-sandboxes) — concepts, architecture, deployment
* [Agent sessions](/stateset-sandbox/stateset-sandbox-agent-sessions) — long-running loops with a cost cap and rotation
* [Webhooks](/stateset-sandbox/stateset-sandbox-webhooks) — the 24 events and HMAC verification


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.