┌─────────────────────────────────────────────────────────────────────────┐
│                              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.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "dev@company.com",
    "organization_name": "Acme Corp",
    "password": "YourSecurePassword123!",
    "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.com',
  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.com',
  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'
  }
});

const session = await client.createReplSession(sandboxId, { language: 'python' });
const result = await client.executeRepl(sandboxId, session.id, { code: 'x = 42' });
// Variables persist across calls
const result2 = await client.executeRepl(sandboxId, session.id, { code: 'print(x * 2)' });
await client.destroyReplSession(sandboxId, session.id);

Authorization: ApiKey sk-sandbox-xxxxxxxxxxxx

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

kubectl apply -f k8s/prometheus/service-monitor.yaml

kubectl label namespace monitoring your-domain.com/monitoring=true

WARM_POOL_ENABLED=true
WARM_POOL_PROFILES='[
  {"cpus":"1","memory":"2Gi","size":6,"isolation":"container"},
  {"cpus":"2","memory":"2Gi","size":4,"isolation":"microvm"}
]'

curl -H "X-Internal-Token: $INTERNAL_API_KEY" \
  "https://api.sandbox.yourdomain.com/api/v1/pool/stats?cpus=1&memory=2Gi&isolation=microvm"

kubectl create secret generic gcs-credentials \
  --from-file=key.json=/path/to/service-account.json \
  -n your-namespace

env:
  - name: GCS_PROJECT_ID
    value: your-gcp-project-id
  - name: GCS_KEY_FILE
    value: /var/secrets/gcp/key.json
volumeMounts:
  - name: gcs-credentials
    mountPath: /var/secrets/gcp
    readOnly: true
volumes:
  - name: gcs-credentials
    secret:
      secretName: gcs-credentials

### Azure Blob Storage (SAS)

Required settings:

- `STORAGE_PROVIDER=azure`
- `STORAGE_BUCKET=your-container`
- `AZURE_STORAGE_ACCOUNT=your-account`
- `AZURE_STORAGE_SAS_TOKEN=sv=...&ss=b&srt=co&sp=rwld&se=...`

Recommended: store `AZURE_STORAGE_SAS_TOKEN` in a Kubernetes Secret and inject it via `env` or `envFrom`.

Optional:

- `AZURE_STORAGE_ENDPOINT=https://your-account.blob.core.windows.net` (sovereign/private clouds)

STATESET_API_URL=https://api.sandbox.stateset.com \
STATESET_API_KEY=sk_sandbox_xxx \
./scripts/verify-gcs-artifacts.sh

# Namespace
apiVersion: v1
kind: Namespace
metadata:
  name: your-namespace

# Controller Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-controller
  namespace: your-namespace
spec:
  replicas: 3
  template:
    spec:
      serviceAccountName: sandbox-controller
      containers:
      - name: controller
        image: REGISTRY_URL/sandbox-controller:latest
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: sandbox-db-url
              key: url
      - name: db-proxy
        image: DB_PROXY_IMAGE
        args:
        - "--structured-logs"
        - "--port=5432"
        - "YOUR_DATABASE_CONNECTION"

kubectl apply -f k8s/crds/

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