Sandbox API Flow

Create, execute, manage files, and tear down a sandbox.

This guide shows a typical end-to-end flow using the Sandbox API.

1) Register and get an API key

curl -X POST https://api.sandbox.stateset.app/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Your", "last_name": "Name", "organization_name": "Company", "email": "[e-mail]"}'

2) Create a sandbox

curl -X POST https://api.sandbox.stateset.app/api/v1/sandbox/create \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout_seconds": 300}'

3) Execute a command

curl -X POST https://api.sandbox.stateset.app/api/v1/sandbox/SANDBOX_ID/execute \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "python3 -c \"print(2 ** 10)\""}'

execute is synchronous and returns when the command exits, so a long build holds the connection open for its whole duration. Bound it with the sandbox’s timeout_seconds rather than your client’s HTTP timeout — a client that gives up first leaves the command running and the sandbox billing.

4) Write a file

curl -X POST https://api.sandbox.stateset.app/api/v1/sandbox/SANDBOX_ID/files/write \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/workspace/hello.txt", "content": "SGVsbG8h", "encoding": "base64"}'

File content is base64 on the way in and on the way out — SGVsbG8h above is Hello!. Sending raw text writes the literal characters of your string, not the bytes you meant.

5) Read a file

curl -X POST https://api.sandbox.stateset.app/api/v1/sandbox/SANDBOX_ID/files/read \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/workspace/hello.txt"}'

This flow creates one sandbox and stops it. When an agent needs to keep working past a single sandbox’s lifetime, use an agent session instead — it carries a budget and rotates the sandbox underneath while keeping context.

6) Stop the sandbox

curl -X POST https://api.sandbox.stateset.app/api/v1/sandbox/SANDBOX_ID/stop \
  -H "Authorization: ApiKey YOUR_API_KEY"

Step 6 is not optional. A sandbox runs, and bills, until it is stopped or its timeout_seconds expires — whichever comes first. Stop it in a finally block rather than at the end of the happy path, or a failed run leaves one up.

Next steps

Sandbox quickstart

The same flow through an SDK rather than curl.

API reference

Every endpoint, with parameters and responses.

Runtime selection

Container, gVisor or MicroVM, and what each costs in start-up time.

Security guide

Before this runs anything you did not write.