Quickstart

Create your first sandbox in minutes.

StateSet Sandbox - Quick Start

Get up and running with StateSet Sandbox in 5 minutes.

1. Get Your API Key

bash

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

Save the api_key from the response - you'll need it!

2. Install the SDK

bash

npm install @stateset/sandbox-sdk

Python:

bash

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

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

const client = new StateSetSandbox({
  baseUrl: 'https://api.sandbox.stateset.app',
  authToken: 'sk-sandbox-YOUR_API_KEY',
  orgId: 'org_YOUR_ORG_ID'
});

async function main() {
  // Create a sandbox
  const sandbox = await client.create({
    timeout_seconds: 300  // 5 minutes
  });

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

  // Run some code
  const result = await client.execute(sandbox.sandbox_id, {
    command: ['python3', '-c', 'print("Hello from StateSet!")']
  });

  console.log(result.stdout);  // "Hello from StateSet!"

  // Clean up
  await client.stop(sandbox.sandbox_id);
}

main();

4. Write and Read Files (Quick Example)

typescript

// Write a file (base64)
await client.writeFiles(sandbox.sandbox_id, [
  { path: '/workspace/hello.txt', content: Buffer.from('Hello!').toString('base64') }
]);

// Read a file (base64)
const file = await client.readFile(sandbox.sandbox_id, '/workspace/hello.txt');
console.log(Buffer.from(file.content, 'base64').toString('utf-8'));

5. What's Next?

**Write files**: client.writeFiles(sandboxId, files)
**Save state**: client.createCheckpoint(sandboxId, options)
**Upload artifacts**: client.uploadArtifact(sandboxId, options)
**Get notified**: client.createWebhook(options)
**Claude Code**: Step-by-step guide in docs/GETTING_STARTED.md#6-integrate-with-claude-cli

Full Example: AI Agent Task

For a fuller Claude Code walkthrough (including MCP tool integration), see docs/GETTING_STARTED.md#6-integrate-with-claude-cli. This example uses the extended client for templates and artifacts.

typescript

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

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

async function runAgentTask(task: string) {
  // Create sandbox with Claude Code pre-installed
  const sandbox = await client.createFromTemplate('claude-agent', {
    timeout_seconds: 600,
    env: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
      TASK: task
    }
  });

  try {
    // Run the agent
    const result = await client.execute(sandbox.sandbox_id, {
      command: ['claude', '-p', task],
      timeout: 300000  // 5 minute timeout for command
    });

    // Save the output
    await client.uploadArtifact(sandbox.sandbox_id, {
      path: '/workspace/output',
      remote_path: `tasks/${Date.now()}/output`
    });

    return {
      success: result.exit_code === 0,
      output: result.stdout,
      errors: result.stderr
    };
  } finally {
    await client.stop(sandbox.sandbox_id);
  }
}

// Usage
const result = await runAgentTask('Create a Python script that fetches weather data');
console.log(result);

Environment Variables

bash

export SANDBOX_API_KEY="sk-sandbox-xxxx"
export SANDBOX_ORG_ID="org_xxxx"
export SANDBOX_BASE_URL="https://api.sandbox.stateset.app"  # optional

Helpful Links

Troubleshooting

**Auth failures (401/403)**

Verify SANDBOX_API_KEY and SANDBOX_ORG_ID are set and valid.
Ensure the API key has access to the org you are targeting.

**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.