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

# StateSet Sandboxes

> Isolated execution for AI agents — provision, run, capture, tear down.

# StateSet Sandboxes

A sandbox is an isolated runtime an agent executes inside. It gets controlled access to tools and
data, its output streams back for audit, and it disappears when you're done.

This is where you run agent code you don't want touching your infrastructure directly.

## The lifecycle

```
create ──▶ execute ──▶ read/write files ──▶ stop
   │                                          │
timeout_seconds is the ceiling ───────────────┘
```

```bash theme={null}
# 1. Provision
curl -X POST https://api.sandbox.stateset.com/api/v1/sandbox/create \
  -H "Authorization: ApiKey $STATESET_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout_seconds": 300}'

# 2. Run something
curl -X POST https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/execute \
  -H "Authorization: ApiKey $STATESET_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "python3 -c \"print(2+2)\""}'

# 3. Tear down — do not wait for the timeout
curl -X POST https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/stop \
  -H "Authorization: ApiKey $STATESET_SANDBOX_API_KEY"
```

<Warning>
  Authentication is **`Authorization: ApiKey <key>`** — not `Bearer`. The rest of the platform uses
  `Bearer`, which makes this the single most common integration mistake here.
</Warning>

## Files

`POST /api/v1/sandbox/:id/files/write` and `/files/read` move data in and out without going through
a shell command.

## Why isolation matters

An agent that can execute code is, by construction, an agent that can execute the *wrong* code. A
sandbox bounds the consequences: a bad run wastes a container and a timeout rather than reaching
your systems.

| Use                  | Why a sandbox                                  |
| -------------------- | ---------------------------------------------- |
| **Agent evaluation** | Test a workflow before it touches production   |
| **Production runs**  | Execution with a clear audit trail             |
| **Multi-tenant**     | Workloads isolated per org                     |
| **Untrusted code**   | Model-generated code runs somewhere disposable |

## Always stop explicitly

```js theme={null}
const sandbox = await create({ timeout_seconds: 300 });
try {
  await run(sandbox);
} finally {
  await stop(sandbox.id);     // even if run() throws
}
```

A sandbox left running bills to its full `timeout_seconds`. The `finally` block is the difference
between a failed run and an expensive one.

## Where sandboxes are used

They back agent execution for [ResponseCX](/stateset-response/responsecx-platform), the
[Console](/stateset-console/stateset-console-overview), and
[iCommerce agent workflows](/stateset-icommerce/stateset-icommerce-agent-sandbox).

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/stateset-sandbox/stateset-sandbox-quickstart-guide">
    First sandbox, end to end.
  </Card>

  <Card title="API reference" icon="code" href="/stateset-sandbox/stateset-sandbox-api-reference">
    Every endpoint.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/stateset-sandbox/stateset-sandbox-architecture">
    Controller, runtime, isolation model.
  </Card>

  <Card title="Security" icon="shield" href="/stateset-sandbox/stateset-sandbox-security-guide">
    Isolation guarantees and hardening.
  </Card>
</CardGroup>