StateSet Sandbox
Sign InGet API Access

Getting Started

SDK usage, file I/O, artifacts, and Claude Code workflows.

Getting Started with StateSet Sandbox

Create, execute, and manage sandboxes using the REST API, Node.js SDK, or Python SDK.

1. Sign Up & Get Your API Key

bash
curl -X POST https://api.sandbox.stateset.app/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Your",
    "last_name": "Name",
    "organization_name": "Your Company",
    "email": "you@example.com"
  }'

Save the api_key.key from the response — you need it for every API call.

2. Store Secrets (BYOK)

Store API keys or credentials so they are automatically injected into every sandbox as environment variables.

Node.js

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

const client = new StateSetSandbox({
  baseUrl: 'https://api.sandbox.stateset.app',
  authToken: process.env.SANDBOX_API_KEY!,
});

await client.createSecret({
  name: 'ANTHROPIC_API_KEY',
  value: process.env.MY_ANTHROPIC_KEY!,
});

Python

python
from stateset_sandbox import StateSetSandbox
import os

client = StateSetSandbox(
    base_url="https://api.sandbox.stateset.app",
    auth_token=os.environ["SANDBOX_API_KEY"],
)

client.create_secret(
    name="ANTHROPIC_API_KEY",
    value=os.environ["MY_ANTHROPIC_KEY"],
)
**Security Note**: All secrets are encrypted at rest using AES-256-GCM. Values are never logged or returned in API responses.

3. Create a Sandbox

Node.js

typescript
const sandbox = await client.create({
  timeout_seconds: 300,
  cpus: '1',
  memory: '1Gi',
});

console.log(`Sandbox created: ${sandbox.sandbox_id}`);

Python

python
sandbox = client.create(
    timeout_seconds=300,
    cpus="1",
    memory="1Gi",
)

print(f"Sandbox created: {sandbox.sandbox_id}")

REST API

bash
export SANDBOX_API_KEY="sk_test_your_api_key_here"

curl -X POST https://api.sandbox.stateset.app/api/v1/sandbox/create \
  -H "Authorization: ApiKey $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "timeout_seconds": 300, "cpus": "1", "memory": "1Gi" }'

4. Execute Commands

Node.js

typescript
// Simple command
const result = await client.execute(sandbox.sandbox_id, {
  command: ['python3', '-c', 'print("Hello!")'],
});
console.log(result.stdout);

// With environment variables and working directory
const result2 = await client.execute(sandbox.sandbox_id, {
  command: ['node', '-e', 'console.log(process.env.API_KEY)'],
  env: { API_KEY: 'secret123' },
  working_dir: '/workspace',
});

// Streaming output
await client.executeStream(sandbox.sandbox_id, {
  command: ['npm', 'install'],
}, {
  onStdout: (data) => console.log(data),
  onStderr: (data) => console.error(data),
  onExit: (code) => console.log('Exit code:', code),
});

Python

python
# Simple command
result = client.execute(sandbox.sandbox_id, command=["python3", "-c", "print('Hello!')"])
print(result.stdout)

# With environment variables
result = client.execute(
    sandbox.sandbox_id,
    command=["node", "-e", "console.log(process.env.API_KEY)"],
    env={"API_KEY": "secret123"},
    working_dir="/workspace",
)

if result.exit_code == 0:
    print("Success:", result.stdout)
else:
    print("Error:", result.stderr)

5. Work with Files

Write Files

Node.js

typescript
// Write a single file (content auto-encoded)
await client.writeFile(sandbox.sandbox_id, '/workspace/hello.py', 'print("Hello!")');

// Write multiple files (content must be base64)
await client.writeFiles(sandbox.sandbox_id, [
  { path: '/workspace/hello.py', content: Buffer.from('print("Hello!")').toString('base64') },
  { path: '/workspace/config.json', content: Buffer.from('{"key": "value"}').toString('base64') },
]);

Python

python
import base64

client.write_files(sandbox.sandbox_id, files=[
    {"path": "/workspace/hello.py", "content": base64.b64encode(b'print("Hello!")').decode()},
    {"path": "/workspace/config.json", "content": base64.b64encode(b'{"key": "value"}').decode()},
])

Read Files

Node.js

typescript
const content = await client.readFileContent(sandbox.sandbox_id, '/workspace/output.txt');
console.log(content);

Python

python
file = client.read_file(sandbox.sandbox_id, "/workspace/output.txt")
content = base64.b64decode(file.content).decode("utf-8")
print(content)

6. Clean Up

Always stop sandboxes when done to avoid unnecessary charges.

Node.js

typescript
await client.stop(sandbox.sandbox_id);

Python

python
client.stop(sandbox.sandbox_id)

Quick Reference

OperationEndpointMethod
Create Sandbox/api/v1/sandbox/createPOST
Get Sandbox/api/v1/sandbox/{id}GET
Execute Command/api/v1/sandbox/{id}/executePOST
Write Files/api/v1/sandbox/{id}/filesPOST
Read File/api/v1/sandbox/{id}/files?path=...GET
Stop Sandbox/api/v1/sandbox/{id}/stopPOST
List Sandboxes/api/v1/sandboxesGET

Environment Variables

bash
export SANDBOX_API_KEY="sk_test_example"
export SANDBOX_BASE_URL="https://api.sandbox.stateset.app"   # Default

What's Next

  • **Node.js SDK** — Express, Next.js, and streaming integration patterns
  • **Python SDK** — FastAPI, Flask, and async patterns
  • **Checkpoints** — Save and restore sandbox state
  • **Agent Sessions** — Long-running AI agent loops with sandbox rotation
  • **Artifacts** — Persistent file storage across sandboxes