StateSet Sandbox Architecture

Scope of this document: a component-level overview suitable for new contributors and integrators. For the deep operational architecture — warm-pool internals, GKE-specific infrastructure, data layer, and event flows — see docs/ARCHITECTURE.md in the sandbox repository, which is the canonical reference. For the Rust-controller-specific architecture see stateset-sandbox-controller/README.md.

Overview

StateSet Sandbox provides an isolated execution environment for running Claude Code CLI and AI agents. The system uses a controller-based architecture where a central API manages ephemeral sandbox pods on Kubernetes.

System Components

1. Sandbox Controller

The controller is a Node.js/Express API that manages the lifecycle of sandbox pods.

Image: YOUR_REGISTRY/stateset/sandbox-controller:latest
Replicas: 3 (high availability)
Namespace: stateset-sandbox
Exposed at: sandbox.stateset.com

Responsibilities:

Authenticate API requests (JWT or API key)
Create/delete sandbox pods via Kubernetes API
Execute commands in running sandboxes
Stream output via SSE or WebSocket
Manage file uploads/downloads
Enforce resource limits and quotas

2. Sandbox Image

The sandbox is a multi-language runtime environment with Claude Code pre-installed.

Image: YOUR_REGISTRY/stateset/sandbox:latest
Not deployed directly - pulled on-demand by the controller

Pre-installed Tools:

Category	Tools
AI/ML	Claude Code CLI, Anthropic SDK
Node.js	Node 22, TypeScript, tsx, ts-node
Python	Python 3.12, pip, anthropic, pydantic
Go	Go 1.22
Rust	Latest stable
MCP Servers	filesystem, github, puppeteer
Dev Tools	Git, GitHub CLI, ESLint, Prettier, Playwright

CI/CD Pipeline Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                            GitLab Push                                       │
│                         (master branch)                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         CI/CD Pipeline                                       │
│                                                                              │
│  Step 1: Build Controller                                                    │
│  ────────────────────────                                                    │
│  docker build --target controller \                                          │
│    -t YOUR_REGISTRY/sandbox-controller:${CI_COMMIT_SHA}    │
│                                                                              │
│  Step 2: Build Sandbox                                                       │
│  ─────────────────────                                                       │
│  docker build --target sandbox \                                             │
│    -t YOUR_REGISTRY/sandbox:${CI_COMMIT_SHA}               │
│                                                                              │
│  Step 3: Push Both Images to Artifact Registry                              │
│                                                                              │
│  Step 4: Deploy Controller Only                                              │
│  ─────────────────────────────                                               │
│  kubectl apply -k k8s/  (deploys sandbox-controller to stateset-sandbox)    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    GKE Cluster (stateset-sandbox namespace)                  │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  sandbox-controller (3 replicas)                                     │    │
│  │  Exposed at: sandbox.stateset.com                    │    │
│  │                                                                      │    │
│  │  ConfigMap:                                                          │    │
│  │  ┌─────────────────────────────────────────────────────────────┐    │    │
│  │  │ SANDBOX_IMAGE: YOUR_REGISTRY/sandbox:latest│    │    │
│  │  │ DEFAULT_CPUS: "2"                                            │    │    │
│  │  │ DEFAULT_MEMORY: "2Gi"                                        │    │    │
│  │  │ NAMESPACE: "stateset-sandbox"                                │    │    │
│  │  └─────────────────────────────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
│  Sandbox pods: (none yet - created on demand)                               │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Runtime Flow

Creating and Using a Sandbox

┌─────────────────────────────────────────────────────────────────────────────┐
│  Your Application                                                            │
│                                                                              │
│  const client = new StateSetSandbox({                                       │
│    baseUrl: 'https://sandbox.stateset.com',                  │
│    authToken: 'sk-...'                                                       │
│  });                                                                         │
│  await client.create();                                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   │ POST /api/sandbox/create
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  sandbox-controller                                                          │
│                                                                              │
│  1. Receives request                                                         │
│  2. Reads SANDBOX_IMAGE from env (ConfigMap)                                │
│  3. Calls K8s API to create pod:                                            │
│     ┌──────────────────────────────────────────────────────────────────┐    │
│     │ apiVersion: v1                                                    │    │
│     │ kind: Pod                                                         │    │
│     │ metadata:                                                         │    │
│     │   name: sandbox-org_xxx-abc123                                   │    │
│     │   namespace: stateset-sandbox                                     │    │
│     │ spec:                                                             │    │
│     │   containers:                                                     │    │
│     │     - image: YOUR_REGISTRY/sandbox:latest       │    │
│     │       env:                                                        │    │
│     │         - name: ANTHROPIC_API_KEY                                │    │
│     │           valueFrom: secretKeyRef...                              │    │
│     └──────────────────────────────────────────────────────────────────┘    │
│  4. Waits for pod to be ready                                               │
│  5. Returns sandbox_id to caller                                            │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Sandbox Pod (ephemeral)                                                     │
│  ────────────────────────                                                    │
│  Image: YOUR_REGISTRY/sandbox:latest                       │
│                                                                              │
│  Pre-installed:                                                              │
│  • Claude Code CLI (@anthropic-ai/claude-code)                              │
│  • Node.js 22, Python 3.12, Go 1.22, Rust                                   │
│  • MCP servers (filesystem, github, puppeteer)                              │
│  • Git, GitHub CLI                                                           │
│                                                                              │
│  Ready to execute commands via kubectl exec                                  │
└─────────────────────────────────────────────────────────────────────────────┘

Command Execution Flow

┌──────────────┐     POST /api/sandbox/{id}/execute      ┌────────────────────┐
│              │ ──────────────────────────────────────► │                    │
│  Your App    │     { "command": "claude -p '...'" }    │  sandbox-controller│
│              │ ◄────────────────────────────────────── │                    │
└──────────────┘     SSE stream: stdout/stderr/exit      └────────────────────┘
                                                                   │
                                                                   │ kubectl exec
                                                                   ▼
                                                         ┌────────────────────┐
                                                         │   Sandbox Pod      │
                                                         │                    │
                                                         │  $ claude -p '...' │
                                                         │  (calls Anthropic) │
                                                         │                    │
                                                         └────────────────────┘

API Endpoints

Sandbox Management

Method	Endpoint	Description
POST	`/api/sandbox/create`	Create a new sandbox
GET	`/api/sandbox/:id`	Get sandbox details
GET	`/api/sandbox/:id/status`	Get sandbox status (lightweight)
GET	`/api/sandboxes`	List all sandboxes
POST	`/api/sandbox/:id/stop`	Stop and delete sandbox
DELETE	`/api/sandbox/:id`	Delete sandbox

File Operations

Method	Endpoint	Description
POST	`/api/sandbox/:id/files`	Write files to sandbox
GET	`/api/sandbox/:id/files?path=...`	Read file (base64)
GET	`/api/sandbox/:id/files/download?path=...`	Download file (binary)

Command Execution

Method	Endpoint	Description
POST	`/api/sandbox/:id/execute`	Execute command (streaming optional)
WS	`/ws`	WebSocket for real-time streaming

Kubernetes Resources

Namespace: `stateset-sandbox`

Resource	Name	Purpose
Deployment	`sandbox-controller`	Controller API (3 replicas)
Service	`sandbox-controller`	ClusterIP for internal access
Ingress	`sandbox-controller`	External access via nginx
ConfigMap	`sandbox-controller-config`	Controller configuration
Secret	`sandbox-controller-auth`	JWT secret, API keys
Secret	`anthropic-credentials`	Anthropic API key for sandboxes
ServiceAccount	`sandbox-controller`	K8s API access for pod management
Role/RoleBinding	`sandbox-controller`	RBAC for pod CRUD operations
NetworkPolicy	`sandbox-controller`	Network isolation rules
ResourceQuota	`sandbox-quota`	Limit total sandbox resources

Docker Build Targets

The unified Dockerfile supports multiple build targets:

# Build controller image
docker build --target controller \
  -t YOUR_REGISTRY/stateset/sandbox-controller:latest .

# Build sandbox image
docker build --target sandbox \
  -t YOUR_REGISTRY/stateset/sandbox:latest .

Target	Base Image	Size	Purpose
`controller`	node:22-slim	~200MB	API server
`sandbox`	node:22-slim	~2.5GB	Full dev environment

SDK Usage

TypeScript SDK

import { StateSetSandbox, AgentRunner } from '@stateset/sandbox-sdk';

// Initialize client
const client = new StateSetSandbox({
  baseUrl: 'https://sandbox.stateset.com',
  authToken: process.env.STATESET_API_KEY!,
  orgId: 'org_xxx'
});

// Low-level: Create sandbox and execute commands
const sandbox = await client.create();
const result = await client.execute(sandbox.sandbox_id, {
  command: 'claude -p "Write a hello world in Python"'
});
console.log(result.stdout);
await client.stop(sandbox.sandbox_id);

// High-level: Use AgentRunner
const runner = new AgentRunner({
  sandbox: client,
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!
});

const { events } = await runner.runAndCleanup({
  prompt: 'Create a REST API using FastAPI',
  systemPrompt: 'You are a senior backend developer',
  maxTurns: 10
});

Security

Sandbox Isolation

Ephemeral pods: Each sandbox is a separate pod, destroyed after use
Non-root user: Sandboxes run as UID 1000 (sandbox user)
Resource limits: CPU/memory limits enforced per sandbox
Network policies: Sandboxes have limited network access
Read-only filesystem: Optional, configurable per deployment
gVisor runtime: Optional sandboxing via RUNTIME_CLASS config

Authentication

API Keys: Authorization: ApiKey sk-...
JWT Tokens: Authorization: Bearer eyJ...
Org isolation: Sandboxes are scoped to organizations

Configuration

Environment Variables (Controller)

Variable	Default	Description
`SANDBOX_IMAGE`	`stateset/sandbox:latest`	Image for sandbox pods
`DEFAULT_CPUS`	`2`	Default CPU limit
`DEFAULT_MEMORY`	`2Gi`	Default memory limit
`DEFAULT_TIMEOUT`	`600`	Sandbox timeout (seconds)
`MAX_SANDBOXES_PER_ORG`	`5`	Max concurrent sandboxes per org
`NAMESPACE`	`stateset-sandbox`	K8s namespace for pods
`LOG_LEVEL`	`info`	Logging verbosity
`RUNTIME_CLASS`	(unset)	Optional: `gvisor` for extra isolation

Directory Structure

stateset-sandbox/
├── Dockerfile                 # Multi-target: controller & sandbox
├── ARCHITECTURE.md           # This file
├── controller/
│   ├── src/
│   │   ├── index.ts          # Express server entrypoint
│   │   ├── routes.ts         # API route handlers
│   │   ├── sandbox-manager.ts # K8s pod management
│   │   └── middleware/
│   │       └── auth.ts       # JWT/API key authentication
│   ├── package.json
│   └── tsconfig.json
├── sdk/
│   └── src/
│       ├── client.ts         # StateSetSandbox client
│       ├── agent-runner.ts   # High-level agent runner
│       └── types.ts          # TypeScript types
├── docker/
│   ├── entrypoint.sh         # Sandbox container entrypoint
│   └── health-check.sh       # Sandbox health check
└── k8s/
    ├── deployment.yaml       # Controller deployment
    ├── service.yaml          # Controller service
    ├── ingress.yaml          # External access
    ├── configmap.yaml        # Controller config
    ├── secret.yaml           # Auth credentials
    ├── rbac.yaml             # ServiceAccount & roles
    ├── network-policy.yaml   # Network isolation
    ├── resource-quota.yaml   # Resource limits
    └── kustomization.yaml    # Kustomize config

Next steps

Runtime selection

Which isolation runtime each component actually runs under.

API reference

The controller surface these components expose.

Security guide

How the boundaries drawn here are enforced.

Deployments

Mapping these components onto a managed Kubernetes cluster.

​StateSet Sandbox Architecture

​Overview

​System Components

​1. Sandbox Controller

​2. Sandbox Image

​CI/CD Pipeline Flow

​Runtime Flow

​Creating and Using a Sandbox

​Command Execution Flow

​API Endpoints

​Sandbox Management

​File Operations

​Command Execution

​Kubernetes Resources

​Namespace: stateset-sandbox

​Docker Build Targets

​SDK Usage

​TypeScript SDK

​Security

​Sandbox Isolation

​Authentication

​Configuration

​Environment Variables (Controller)

​Directory Structure

​Next steps