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

# Agent Sandbox Costs

> The levers that actually control sandbox spend — timeout, sizing, batching, and lifecycle.

# Agent Sandbox Costs

Sandbox cost is a function of **how long you hold resources**, not how much work you do. The levers
below are ordered by how much they typically save.

## 1. Timeout is the main lever

`timeout_seconds` is the ceiling on what a run can cost. Set it to slightly more than the work
needs, not to a comfortable round number.

```bash theme={null}
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": 120, "cpus": 1, "memory": 512}'
```

<Warning>
  A hung agent bills for the full timeout. The default is generous enough that a stuck loop is
  expensive — this is the single most common source of surprise cost.
</Warning>

## 2. Stop explicitly, don't wait for the timeout

```bash theme={null}
curl -X POST https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/stop \
  -H "Authorization: ApiKey $STATESET_SANDBOX_API_KEY"
```

Stop in a `finally` block so a thrown error doesn't leave the sandbox running to its ceiling:

```js theme={null}
const sandbox = await createSandbox({ timeout_seconds: 120 });
try {
  await run(sandbox);
} finally {
  await stopSandbox(sandbox.id);   // always
}
```

## 3. Size to the workload

`cpus` and `memory` should match what the agent actually needs. A commerce agent doing reads and a
few writes is not a compute-heavy job — oversizing pays for headroom that goes unused for the whole
run.

## 4. Batch deliberately

| Shape                      | When it's cheaper                                        |
| -------------------------- | -------------------------------------------------------- |
| Many short-lived sandboxes | Bursty, independent tasks — you pay only for each burst  |
| One reused sandbox         | A long workflow with shared state, where setup dominates |

Splitting a large workflow into smaller runs bounds the blast radius of a failure too: a run that
dies takes one chunk's spend with it rather than the whole job's.

## Keep the cost visible

Stream and store execution output. Two reasons: an audit trail for what the agent did, and the
evidence for *why* a run cost what it did.

```bash theme={null}
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": "stateset --json \"show me pending orders\""}'
```

<Tip>
  Use `--json` for agent-driven commands. Beyond being parseable, it's more compact than prose output
  — which matters when the output is going back into a model's context and being paid for by the
  token.
</Tip>

## Guardrails that also save money

`--apply` prevents an exploring agent from doing expensive write work by accident. Scoping its
tools narrows what it can attempt at all. A run that can't call the manufacturing domain won't
spend time deciding whether to.

## Related

* [Agent Sandbox](/stateset-icommerce/stateset-icommerce-agent-sandbox)
* [Sandbox Runbook](/stateset-icommerce/stateset-icommerce-agent-sandbox-runbook)
* [Sandbox Operations](/stateset-sandbox/stateset-sandbox-operations)