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

Hosted API quickstart

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

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":"[e-mail]"}'

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}'

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

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.

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.