> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Quickstart Guide

> Get a StateSet Sandbox running and execute your first code.

# StateSet Sandbox - Quick Start

Get up and running with StateSet Sandbox in 5 minutes.

## 1. Get Your API Key

```bash theme={null}
curl -X POST https://api.sandbox.stateset.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Your",
    "last_name": "Name",
    "organization_name": "Your Company",
    "email": "you@company.com",
    "password": "YourSecurePassword123!"
  }'
```

Save the `api_key` from the response — you'll need it!

```bash theme={null}
export STATESET_API_KEY="sk-sandbox-YOUR_API_KEY"
```

## 2. Install the SDK

**TypeScript / Node.js:**

```bash theme={null}
npm install @stateset/sandbox-sdk
```

**Python:**

```bash theme={null}
pip install stateset-sandbox
```

Other language SDKs (preview) are available in this repo:

* Rust: `sdk-rust/README.md`
* Ruby: `sdk-ruby/README.md`
* Go: `sdk-go/README.md`
* PHP: `sdk-php/README.md`
* Java: `sdk-java/README.md`
* Kotlin: `sdk-kotlin/README.md`
* Swift: `sdk-swift/README.md`

## 3. Create Your First Sandbox

### TypeScript

```typescript theme={null}
import { Sandbox } from '@stateset/sandbox-sdk';

const sandbox = await Sandbox.create();

const result = await sandbox.exec('echo "Hello from StateSet!"');
console.log(result.stdout); // Hello from StateSet!

await sandbox.close();
```

### Python

```python theme={null}
from stateset_sandbox import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.exec('echo "Hello from StateSet!"')
    print(result.stdout)  # Hello from StateSet!
```

### cURL

```bash theme={null}
# Create a sandbox
SANDBOX_ID=$(curl -s -X POST https://api.sandbox.stateset.com/api/v1/sandbox \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout_seconds": 300}' | jq -r '.sandbox_id')

# Execute a command
curl -s -X POST "https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/execute" \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "echo Hello from StateSet!"}' | jq .

# Clean up
curl -s -X POST "https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/stop" \
  -H "Authorization: Bearer $STATESET_API_KEY"
```

## 4. Write and Read Files

### TypeScript

```typescript theme={null}
import { Sandbox } from '@stateset/sandbox-sdk';

const sandbox = await Sandbox.create();

// Write a file
await sandbox.writeFile('/workspace/hello.py', 'print("Hello world!")');

// Run it
const result = await sandbox.exec('python /workspace/hello.py');
console.log(result.stdout); // Hello world!

// Read it back
const content = await sandbox.readFile('/workspace/hello.py');
console.log(content); // print("Hello world!")

await sandbox.close();
```

### Python

```python theme={null}
from stateset_sandbox import Sandbox

with Sandbox.create() as sandbox:
    sandbox.write_file("/workspace/hello.py", 'print("Hello world!")')
    result = sandbox.exec("python /workspace/hello.py")
    print(result.stdout)  # Hello world!
```

## 5. Interactive REPL Sessions

REPL sessions let you execute code interactively with persistent state across calls — ideal for data exploration, iterative development, and AI agent workflows.

> **Note:** Requires `REPL_ENABLED=true` on the controller.

### cURL

```bash theme={null}
# Create an interactive Python REPL session
SESSION_ID=$(curl -s -X POST "https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/repl/sessions" \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "python"}' | jq -r '.session_id')

# Execute code (variables persist across calls)
curl -s -X POST "https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/repl/sessions/$SESSION_ID/execute" \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "import pandas as pd\ndf = pd.DataFrame({\"a\": [1,2,3]})"}'

# Variables persist — reference df from previous execution
curl -s -X POST "https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/repl/sessions/$SESSION_ID/execute" \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "print(df.describe())"}'

# Destroy session when done
curl -s -X DELETE "https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/repl/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $STATESET_API_KEY"
```

### TypeScript

```typescript theme={null}
import { Sandbox } from '@stateset/sandbox-sdk';

const sandbox = await Sandbox.create();

// Create a REPL session
const session = await sandbox.createReplSession({ language: 'python' });

// Execute code with persistent state
const result1 = await sandbox.executeRepl(session.id, { code: 'x = 42' });
const result2 = await sandbox.executeRepl(session.id, { code: 'print(x * 2)' });
console.log(result2.outputs[0].text); // 84

// Clean up
await sandbox.destroyReplSession(session.id);
await sandbox.close();
```

## 6. Choose a Template

Templates pre-configure your sandbox with the right tools:

```typescript theme={null}
// Base (default) — Node.js, Python, Git
const sandbox = await Sandbox.create();

// Claude Code — Claude CLI, Agent SDK, MCP servers
const sandbox = await Sandbox.create({ template: 'claude-code' });

// Browser — Playwright + Chromium
const sandbox = await Sandbox.create({ template: 'browser' });

// Computer-use — GUI actions with Xvfb, xdotool, and browser tooling
const sandbox = await Sandbox.create({ template: 'computer-use' });

// Computer-use benchmark — lower footprint profile for benchmark runs
const sandbox = await Sandbox.create({ template: 'computer-use-benchmark' });

// Rust development
const sandbox = await Sandbox.create({ template: 'rust' });

// Go development
const sandbox = await Sandbox.create({ template: 'go' });
```

### Validate Computer-Use Template (optional)

```bash theme={null}
export STATESET_API_KEY="sk-sandbox-..."
bash scripts/computer-use-smoke.sh --url https://example.com
```

## 7. Use with AI Frameworks

StateSet Sandbox integrates with popular AI frameworks so your agents can execute code safely:

### LangChain

```bash theme={null}
pip install stateset-langchain
```

```python theme={null}
from stateset_langchain import SandboxToolkit

with SandboxToolkit.create() as toolkit:
    tools = toolkit.get_tools()
    # Use with any LangChain agent...
```

Full LangChain Guide →

### OpenAI Function Calling

```bash theme={null}
pip install stateset-openai
```

```python theme={null}
from stateset_openai import SandboxToolkit

with SandboxToolkit.create() as toolkit:
    response = client.chat.completions.create(
        model="gpt-4o",
        tools=toolkit.tool_definitions(),
        messages=messages,
    )
```

Full OpenAI Guide →

### Vercel AI SDK

```bash theme={null}
npm install @stateset/ai-sdk-sandbox
```

```typescript theme={null}
import { createSandboxTools } from '@stateset/ai-sdk-sandbox';

const { tools, cleanup } = await createSandboxTools();
const { text } = await generateText({ model, tools, maxSteps: 10, prompt });
await cleanup();
```

Full Vercel AI SDK Guide →

## 8. Full Example: AI Agent Task

```typescript theme={null}
import { Sandbox } from '@stateset/sandbox-sdk';

async function runAgentTask(task: string) {
  const sandbox = await Sandbox.create({
    template: 'claude-code',
    cpus: '2',
    memory: '4Gi',
    timeout_seconds: 600,
  });

  try {
    const result = await sandbox.exec(`claude -p "${task}"`);
    return {
      success: result.exit_code === 0,
      output: result.stdout,
      errors: result.stderr,
    };
  } finally {
    await sandbox.close();
  }
}

const result = await runAgentTask('Create a Python weather API');
console.log(result.output);
```

## Environment Variables

```bash theme={null}
export STATESET_API_KEY="sk-sandbox-xxxx"
export STATESET_BASE_URL="https://api.sandbox.stateset.com"  # optional
```

## What's Next?

* Python SDK Guide — full Python reference
* Node.js SDK Guide — full TypeScript reference
* LangChain Guide — build LangChain agents with sandboxes
* OpenAI Guide — OpenAI function calling integration
* Vercel AI SDK Guide — AI SDK tool integration
* Templates Guide — all available sandbox templates
* API Reference — full REST API documentation
* Production Guide — deployment and operations

## Troubleshooting

**Auth failures (401/403)**

* Verify `STATESET_API_KEY` is set and valid.
* For API key auth (non-JWT), ensure the key belongs to your org.

**Rate limits or plan limits**

* Check your plan's max runtime and concurrent sandbox limits.
* Reduce CPU/memory or shorten timeouts if you hit rate limits.

**Command timeouts**

* Increase `timeout` for long-running commands (up to 10 minutes).
* Prefer smaller steps and check stdout/stderr for partial output.

**Artifacts return 404**

* Artifact routes require `ARTIFACTS_ENABLED=true` and storage config.