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_..."