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, 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

​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