Skip to main content
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":"[email protected]"}'

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

MethodPathDescription
POST/api/v1/sandbox/createCreate a new sandbox
GET/api/v1/sandbox/:idGet sandbox details
GET/api/v1/sandbox/:id/statusGet sandbox status
GET/api/v1/sandboxesList sandboxes
POST/api/v1/sandbox/:id/filesWrite files to a sandbox
GET/api/v1/sandbox/:id/files?path=...Read a file from a sandbox
POST/api/v1/sandbox/:id/executeExecute a command
POST/api/v1/sandbox/:id/stopStop and delete a sandbox
DELETE/api/v1/sandbox/:idDelete a sandbox

​
Configuration highlights

VariableDefaultDescription
SANDBOX_IMAGE-Base image for sandbox pods
DEFAULT_CPUS2Default CPU limit
DEFAULT_MEMORY2GiDefault memory limit
DEFAULT_TIMEOUT600Default timeout in seconds
MAX_SANDBOXES_PER_ORG5Max concurrent sandboxes per org
SANDBOX_EXEC_BACKENDkubectlCommand exec backend
WARM_POOL_ENABLEDfalseEnable 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.