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

> Self-hosted Kubernetes sandbox for running AI agents with full code execution in isolated containers

StateSet Sandbox is a Kubernetes-based sandbox infrastructure for running code execution workloads inside isolated pods. It exposes REST and WebSocket APIs for creating sandboxes, streaming command output, and reading or writing files inside each sandbox workspace.

## Key capabilities

* Isolated execution per sandbox pod with resource limits
* REST and WebSocket APIs for command execution and streaming output
* File read and write APIs for workspace workflows
* Prebuilt runtime with Node.js, Python, Go, Rust, and common CLI tooling
* Automatic cleanup with per-sandbox timeouts
* Optional warm pool support for faster startup

## Architecture overview

```mermaid theme={null}
graph LR
  Client[Your app or agent runner] -->|HTTP or WebSocket| Controller[Sandbox controller]
  Controller -->|Kubernetes API| Pod[Sandbox pod]
  Pod --> Workspace[/workspace/]
```

## Hosted API quickstart

1. Register and receive an API key.
2. Create a sandbox with a timeout.
3. Execute commands inside the sandbox.

```bash theme={null}
curl -X POST https://api.sandbox.StateSet.app/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Ada","last_name":"Lovelace","organization_name":"Example Co","email":"ada@example.com"}'
```

```bash theme={null}
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}'
```

```bash theme={null}
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(Hello World!)\""}'
```

## TypeScript SDK example

```ts theme={null}
import { StateSetSandbox } from "@StateSet/sandbox-sdk";

const sandbox = new StateSetSandbox({
  baseUrl: "https://api.sandbox.StateSet.app",
  authToken: "sk-sandbox-your-api-key",
  timeout: 120000,
});

const instance = await sandbox.create({
  cpus: "2",
  memory: "2Gi",
  timeout_seconds: 300,
});

await sandbox.writeFile(
  instance.sandbox_id,
  "/workspace/hello.js",
  'logger.info("Hello from sandbox!");'
);

const result = await sandbox.execute(instance.sandbox_id, {
  command: "node /workspace/hello.js",
});

logger.info(result.stdout);
await sandbox.stop(instance.sandbox_id);
```

## Self-hosted deployment

At a high level, deployment includes:

1. Build and push the sandbox and controller images.
2. Apply the Kubernetes manifests in `k8s/`.
3. Configure secrets for JWT signing and provider keys.
4. Deploy the controller and verify pod creation.

```bash theme={null}
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/rbac.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/deployment.yaml
```

## API summary

| Method | Path                                 | Description                |
| ------ | ------------------------------------ | -------------------------- |
| POST   | `/api/v1/sandbox/create`             | Create a new sandbox       |
| GET    | `/api/v1/sandbox/:id`                | Get sandbox details        |
| GET    | `/api/v1/sandbox/:id/status`         | Get sandbox status         |
| GET    | `/api/v1/sandboxes`                  | List sandboxes             |
| POST   | `/api/v1/sandbox/:id/files`          | Write files to a sandbox   |
| GET    | `/api/v1/sandbox/:id/files?path=...` | Read a file from a sandbox |
| POST   | `/api/v1/sandbox/:id/execute`        | Execute a command          |
| POST   | `/api/v1/sandbox/:id/stop`           | Stop and delete a sandbox  |
| DELETE | `/api/v1/sandbox/:id`                | Delete a sandbox           |

## Configuration highlights

| Variable                | Default   | Description                      |
| ----------------------- | --------- | -------------------------------- |
| `SANDBOX_IMAGE`         | -         | Base image for sandbox pods      |
| `DEFAULT_CPUS`          | `2`       | Default CPU limit                |
| `DEFAULT_MEMORY`        | `2Gi`     | Default memory limit             |
| `DEFAULT_TIMEOUT`       | `600`     | Default timeout in seconds       |
| `MAX_SANDBOXES_PER_ORG` | `5`       | Max concurrent sandboxes per org |
| `SANDBOX_EXEC_BACKEND`  | `kubectl` | Command exec backend             |
| `WARM_POOL_ENABLED`     | `false`   | Enable warm pool pods            |

## Security and isolation

* Sandboxes run as non-root with dropped Linux capabilities.
* Seccomp profiles and resource limits are enforced at the pod level.
* Network policies restrict egress to HTTPS and DNS.