┌─────────────────────────────────────────────────────────────────────────┐
│                              DEVELOPER                                   │
└─────────────────────────────────────────────────────────────────────────┘
         │                           │                          │
         │ 1. Register               │ 2. Use SDK              │ 3. Dashboard
         ▼                           ▼                          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         SANDBOX CONTROLLER                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐  │
│  │ Registration │  │   Sandbox    │  │  Checkpoint  │  │   Webhook   │  │
│  │   Service    │  │   Manager    │  │   Manager    │  │   Manager   │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬──────┘  │
└─────────┼─────────────────┼─────────────────┼─────────────────┼─────────┘
          │                 │                 │                 │
          ▼                 ▼                 ▼                 ▼
┌─────────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐
│   PostgreSQL    │  │ Kubernetes  │  │ Cloud       │  │ External        │
│ (Managed DB)   │  │ (Pods)      │  │ Storage     │  │ Webhooks        │
│                 │  │             │  │ (GCS/S3)    │  │                 │
│ • organizations │  │ • sandbox   │  │ • artifacts │  │ • your-app.com  │
│ • api_keys      │  │   pods      │  │ • checkpts  │  │                 │
│ • usage_events  │  │             │  │             │  │                 │
│ • checkpoints   │  │             │  │             │  │                 │
└─────────────────┘  └─────────────┘  └─────────────┘  └─────────────────┘

curl -X POST https://api.sandbox.stateset.app/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "dev@company.com",
    "organization_name": "Acme Corp",
    "use_case": "CI automation"
  }'

{
  "organization": {
    "id": "org_abc123",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "hobby"
  },
  "user": {
    "id": "user_abc123",
    "email": "dev@company.com",
    "role": "owner"
  },
  "api_key": {
    "key": "sk-sandbox-xxxxxxxxxxxxxxxxxxxx",
    "key_prefix": "sk-sandbox-xxxx",
    "name": "Default API Key"
  }
}

npm install @stateset/sandbox-sdk

pip install stateset-sandbox

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

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

// Create a sandbox
const sandbox = await client.create({
  timeout_seconds: 300, // 5 minutes
  cpus: '1',           // 1 vCPU
  memory: '1Gi',       // 1GB RAM
  env: {
    NODE_ENV: 'production'
  }
});

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

// Execute commands
const result = await client.execute(sandbox.sandbox_id, {
  command: ['node', '-e', 'console.log("Hello from sandbox!")']
});

console.log(result.stdout);  // "Hello from sandbox!"
console.log(result.exit_code); // 0

// Write files
await client.writeFiles(sandbox.sandbox_id, [
  { path: '/workspace/app.js', content: 'console.log("app");' }
]);

// Read files
const content = await client.readFile(sandbox.sandbox_id, '/workspace/app.js');

// Stop sandbox when done
await client.stop(sandbox.sandbox_id);

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

const client = new StateSetSandboxExtended({
  baseUrl: 'https://api.sandbox.stateset.app',
  authToken: 'sk-sandbox-xxxxxxxxxxxx'
});

// Save current state
const checkpoint = await client.createCheckpoint(sandbox.sandbox_id, {
  name: 'after-npm-install',
  description: 'All dependencies installed'
});

console.log(`Checkpoint created: ${checkpoint.id}`);

// Later: Restore to that state (same sandbox)
await client.restoreCheckpoint(sandbox.sandbox_id, checkpoint.id, {
  restore_files: true,
  restore_env: true,
  overwrite: true
});

// Clone a checkpoint
const cloned = await client.cloneCheckpoint(checkpoint.id, 'feature-branch-base');

// Compare checkpoints
const diff = await client.compareCheckpoints(
  checkpoint1.id,
  checkpoint2.id
);

// Upload file from sandbox to cloud storage
const artifact = await client.uploadArtifact(sandbox.sandbox_id, {
  path: '/workspace/output/report.pdf',
  remote_path: 'reports/2024/report.pdf', // stored under artifacts/<organization-id>/...
  content_type: 'application/pdf',
  expires_in: 86400 * 7  // 7 days
});

// Download artifact to sandbox
await client.downloadArtifact(
  sandbox.sandbox_id,
  artifact.id,
  '/workspace/downloads/report.pdf'
);

// Get presigned URL for direct download
const { url } = await client.getArtifactUrl(artifact.id, 3600);
console.log(`Artifact URL: ${url}`);

// Register webhook
const webhook = await client.createWebhook({
  url: 'https://your-app.com/webhooks/sandbox',
  events: [
    'sandbox.created',
    'sandbox.ready',
    'sandbox.error',
    'sandbox.stopped',
    'command.completed',
    'checkpoint.created'
  ],
  secret: 'whsec_your_secret_key'
});

// Test webhook
const testResult = await client.testWebhook(webhook.id);
console.log(`Test successful: ${testResult.success}`);

// List webhook deliveries
const deliveries = await client.getWebhookDeliveries(webhook.id, 10);

{
  "id": "evt_abc123",
  "event": "sandbox.ready",
  "timestamp": "2024-01-15T12:00:00Z",
  "sandboxId": "sbx_xyz789",
  "orgId": "org_abc123",
  "data": {
    "podIp": "10.0.1.5",
    "startupMs": 1234
  }
}

import { createHmac } from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

// List available templates
const templates = await client.listTemplates();

// Create from template
const sandbox = await client.createFromTemplate('python-data-science', {
  timeout_seconds: 600,
  env: {
    DATASET_URL: 'https://example.com/data.csv'
  }
});

Authorization: ApiKey sk-sandbox-xxxxxxxxxxxx

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Controller logs
kubectl logs -n your-namespace -l app=sandbox-controller -c controller

# Database proxy logs
kubectl logs -n your-namespace -l app=sandbox-controller -c db-proxy

# Sandbox pod logs
kubectl logs -n your-namespace <sandbox-pod-name>