Skip to main content

Code Examples

Real-world examples showing how to use Caged for common AI agent workflows.

Run Claude Code in a Sandbox

import { Caged } from "@caged-dev/sdk";

const caged = new Caged({ apiKey: process.env.CAGED_API_KEY! });

// Create sandbox with repo
const sandbox = await caged.sandboxes.create({
  template: "node-20",
  cpus: 4,
  memory_mb: 2048,
  repo: "https://github.com/myorg/myapp",
  repo_branch: "feature/new-api",
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  budget: 5.0, // $5 cap
});

// Connect via MCP WebSocket
const mcpUrl = `wss://api.caged.dev/v1/sandboxes/${sandbox.id}/mcp`;
// ... connect your MCP client here ...

// When done, snapshot and destroy
await caged.snapshots.create(sandbox.id, { name: "session-end" });
await caged.sandboxes.destroy(sandbox.id);

CI/CD: Test PRs in Isolated Environments

import { Caged } from "@caged-dev/sdk";

const caged = new Caged({ apiKey: process.env.CAGED_API_KEY! });

async function testPR(repoUrl: string, branch: string) {
  const sandbox = await caged.sandboxes.create({
    template: "node-20",
    repo: repoUrl,
    repo_branch: branch,
    init_script: "npm ci && npm test",
    timeout: 300,
  });

  // Wait for tests to complete, then check results
  const files = await caged.files.list(sandbox.id, "/workspace");
  const diff = await caged.files.gitDiff(sandbox.id);

  console.log("Changes:", diff);
  await caged.sandboxes.destroy(sandbox.id);
}

Fork a Sandbox via Snapshot

import { Caged } from "@caged-dev/sdk";

const caged = new Caged({ apiKey: process.env.CAGED_API_KEY! });

async function forkSandbox(sourceId: string): Promise<string> {
  // Snapshot the source
  const snap = await caged.snapshots.create(sourceId, { name: "fork-source" });

  // Wait for snapshot to complete
  let snapshot = await caged.snapshots.get(snap.id);
  while (snapshot.status === "pending") {
    await new Promise((r) => setTimeout(r, 1000));
    snapshot = await caged.snapshots.get(snap.id);
  }

  // Create new sandbox and restore
  const source = await caged.sandboxes.get(sourceId);
  const fork = await caged.sandboxes.create({
    template: source.template,
    cpus: source.cpus,
    memory_mb: source.memory_mb,
  });

  await caged.snapshots.restore(snap.id);
  return fork.id;
}

Batch Processing with Multiple Sandboxes

import { Caged } from "@caged-dev/sdk";

const caged = new Caged({ apiKey: process.env.CAGED_API_KEY! });

async function processInParallel(tasks: string[]) {
  // Spin up sandboxes in parallel
  const sandboxes = await Promise.all(
    tasks.map((task) =>
      caged.sandboxes.create({
        template: "python-312",
        env: { TASK: task },
        init_script: "python /workspace/run.py",
        timeout: 120,
      })
    )
  );

  console.log(`Launched ${sandboxes.length} sandboxes`);

  // Clean up when done
  await Promise.all(sandboxes.map((sb) => caged.sandboxes.destroy(sb.id)));
}

Using with cURL (No SDK)

If you prefer raw HTTP:
# Create a sandbox
curl -X POST https://api.caged.dev/v1/sandboxes \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "node-20",
    "cpus": 2,
    "memory_mb": 1024,
    "repo": "https://github.com/user/repo"
  }'

# Run a command (or prompt an agent)
curl -X POST https://api.caged.dev/v1/sandboxes/cage_abc123/exec \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"command": "npm test"}'

# Check status
curl https://api.caged.dev/v1/sandboxes/cage_abc123 \
  -H "Authorization: Bearer caged_sk_..."

# Read a file
curl "https://api.caged.dev/v1/sandboxes/cage_abc123/files/content?path=/workspace/output.json" \
  -H "Authorization: Bearer caged_sk_..."

# Destroy
curl -X DELETE https://api.caged.dev/v1/sandboxes/cage_abc123 \
  -H "Authorization: Bearer caged_sk_..."