> ## 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 live controller's own OpenAPI.

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>` — this engine's scheme really is `ApiKey`, not `Bearer`                                                                            |
| Spec     | `GET /openapi.json` — this tab is the live document, plus six routes the server serves behind auth but does not publish (each marked on its page, verified live) |
| 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