StateSet API Docs

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

Register and receive an API key.
Create a sandbox with a timeout.
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":"ada@example.com"}'

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);

Hosted and self-hosted are the same controller and API, so code written against one runs unchanged against the other. Start hosted; move to self-hosted when isolation or data residency requires it, not because the API is different.

Self-hosted deployment

At a high level, deployment includes:

Build and push the sandbox and controller images.
Apply the Kubernetes manifests in k8s/.
Configure secrets for JWT signing and provider keys.
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.

Next steps

Sandbox quickstart

The hosted path in full.

Deployments

Self-hosting on EKS, GKE or AKS.

Security guide

Isolation before untrusted code runs.

Node SDK

The typed client used above.

Last modified on August 31, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Running the StateSet iCommerce Sandbox Engine

Key capabilities

Architecture overview

Hosted API quickstart

TypeScript SDK example

Self-hosted deployment

API summary

Configuration highlights

Security and isolation

Next steps

Sandbox quickstart

Deployments

Security guide

Node SDK

​Key capabilities

​Architecture overview

​Hosted API quickstart

​TypeScript SDK example

​Self-hosted deployment

​API summary

​Configuration highlights

​Security and isolation

​Next steps

Sandbox quickstart

Deployments

Security guide

Node SDK

Key capabilities

Architecture overview

Hosted API quickstart

TypeScript SDK example

Self-hosted deployment

API summary

Configuration highlights

Security and isolation

Next steps