---
title: Code Examples
description: "Common use cases and patterns for the Caged SDKs."
---

# Code Examples

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

## Run Claude Code in a Sandbox

<CodeGroup>
```typescript title="TypeScript"
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);
```

```python title="Python"
from caged import Caged
import os

caged = Caged(api_key=os.environ["CAGED_API_KEY"])

# Create sandbox with repo
sandbox = 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": os.environ["ANTHROPIC_API_KEY"]},
    budget=5.00,  # $5 cap
)

# Connect via MCP WebSocket
mcp_url = f"wss://api.caged.dev/v1/sandboxes/{sandbox.id}/mcp"
# ... connect your MCP client here ...

# When done, snapshot and destroy
caged.snapshots.create(sandbox.id, name="session-end")
caged.sandboxes.destroy(sandbox.id)
```
</CodeGroup>

## CI/CD: Test PRs in Isolated Environments

<CodeGroup>
```typescript title="TypeScript"
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);
}
```

```python title="Python"
from caged import Caged

caged = Caged(api_key="caged_sk_...")

def test_pr(repo_url: str, branch: str):
    sandbox = caged.sandboxes.create(
        template="node-20",
        repo=repo_url,
        repo_branch=branch,
        init_script="npm ci && npm test",
        timeout=300,
    )

    # Wait for tests to complete, then check results
    files = caged.files.list(sandbox.id, "/workspace")
    diff = caged.files.git_diff(sandbox.id)

    print(f"Changes: {diff}")
    caged.sandboxes.destroy(sandbox.id)
```
</CodeGroup>

## Fork a Sandbox via Snapshot

<CodeGroup>
```typescript title="TypeScript"
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;
}
```

```python title="Python"
import time
from caged import Caged

caged = Caged(api_key="caged_sk_...")

def fork_sandbox(source_id: str) -> str:
    # Snapshot the source
    snap = caged.snapshots.create(source_id, name="fork-source")

    # Wait for completion
    snapshot = caged.snapshots.get(snap.id)
    while snapshot.status == "pending":
        time.sleep(1)
        snapshot = caged.snapshots.get(snap.id)

    # Create new sandbox and restore
    source = caged.sandboxes.get(source_id)
    fork = caged.sandboxes.create(
        template=source.template,
        cpus=source.cpus,
        memory_mb=source.memory_mb,
    )

    caged.snapshots.restore(snap.id)
    return fork.id
```
</CodeGroup>

## Batch Processing with Multiple Sandboxes

<CodeGroup>
```typescript title="TypeScript"
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)));
}
```

```python title="Python"
import concurrent.futures
from caged import Caged

caged = Caged(api_key="caged_sk_...")

def process_task(task: str):
    sandbox = caged.sandboxes.create(
        template="python-312",
        env={"TASK": task},
        init_script="python /workspace/run.py",
        timeout=120,
    )
    # ... wait for result ...
    caged.sandboxes.destroy(sandbox.id)
    return sandbox.id

def process_in_parallel(tasks: list[str]):
    with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
        futures = [executor.submit(process_task, t) for t in tasks]
        results = [f.result() for f in concurrent.futures.as_completed(futures)]
    print(f"Processed {len(results)} tasks")
```
</CodeGroup>

## Using with cURL (No SDK)

If you prefer raw HTTP:

```bash
# 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_..."
```