adding vercel sandbox with examples and docs (#47)

examples/vercel/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@sandbox-agent/example-vercel",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx src/vercel.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@vercel/sandbox": "latest",
+    "@sandbox-agent/example-shared": "workspace:*",
+    "sandbox-agent": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "tsx": "latest",
+    "typescript": "latest",
+    "vitest": "^3.0.0"
+  }
+}

examples/vercel/src/vercel.ts

@@ -0,0 +1,87 @@
+import { Sandbox } from "@vercel/sandbox";
+import { logInspectorUrl, runPrompt, waitForHealth } from "@sandbox-agent/example-shared";
+
+export async function setupVercelSandboxAgent(): Promise<{
+  baseUrl: string;
+  token?: string;
+  cleanup: () => Promise<void>;
+}> {
+  // Build env vars for agent API keys
+  const envs: Record<string, string> = {};
+  if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
+  if (process.env.OPENAI_API_KEY) envs.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+
+  // Create sandbox with port 3000 exposed
+  const sandbox = await Sandbox.create({
+    runtime: "node24",
+    ports: [3000],
+  });
+
+  // Helper to run commands and check exit code
+  const run = async (cmd: string, args: string[] = []) => {
+    const result = await sandbox.runCommand({ cmd, args, env: envs });
+    if (result.exitCode !== 0) {
+      const stderr = await result.stderr();
+      throw new Error(`Command failed: ${cmd} ${args.join(" ")}\n${stderr}`);
+    }
+    return result;
+  };
+
+  console.log("Installing sandbox-agent...");
+  await run("sh", ["-c", "curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"]);
+
+  console.log("Installing agents...");
+  await run("sandbox-agent", ["install-agent", "claude"]);
+  await run("sandbox-agent", ["install-agent", "codex"]);
+
+  console.log("Starting server...");
+  await sandbox.runCommand({
+    cmd: "sandbox-agent",
+    args: ["server", "--no-token", "--host", "0.0.0.0", "--port", "3000"],
+    env: envs,
+    detached: true,
+  });
+
+  const baseUrl = sandbox.domain(3000);
+
+  console.log("Waiting for server...");
+  await waitForHealth({ baseUrl });
+
+  const cleanup = async () => {
+    console.log("Cleaning up...");
+    await sandbox.stop();
+  };
+
+  return { baseUrl, cleanup };
+}
+
+// Run interactively if executed directly
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  // Check for Vercel auth
+  if (!process.env.VERCEL_OIDC_TOKEN && !process.env.VERCEL_ACCESS_TOKEN) {
+    throw new Error("Vercel authentication required. Run 'vercel env pull' or set VERCEL_ACCESS_TOKEN");
+  }
+
+  if (!process.env.OPENAI_API_KEY && !process.env.ANTHROPIC_API_KEY) {
+    throw new Error("OPENAI_API_KEY or ANTHROPIC_API_KEY required");
+  }
+
+  const { baseUrl, cleanup } = await setupVercelSandboxAgent();
+  logInspectorUrl({ baseUrl });
+
+  process.once("SIGINT", async () => {
+    await cleanup();
+    process.exit(0);
+  });
+  process.once("SIGTERM", async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  await runPrompt({
+    baseUrl,
+    autoApprovePermissions: process.env.AUTO_APPROVE_PERMISSIONS === "true",
+  });
+  await cleanup();
+}

examples/vercel/tests/vercel.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { buildHeaders } from "@sandbox-agent/example-shared";
+import { setupVercelSandboxAgent } from "../src/vercel.ts";
+
+const shouldRun = Boolean(process.env.VERCEL_OIDC_TOKEN || process.env.VERCEL_ACCESS_TOKEN);
+const timeoutMs = Number.parseInt(process.env.SANDBOX_TEST_TIMEOUT_MS || "", 10) || 300_000;
+
+const testFn = shouldRun ? it : it.skip;
+
+describe("vercel example", () => {
+  testFn(
+    "starts sandbox-agent and responds to /v1/health",
+    async () => {
+      const { baseUrl, token, cleanup } = await setupVercelSandboxAgent();
+      try {
+        const response = await fetch(`${baseUrl}/v1/health`, {
+          headers: buildHeaders({ token }),
+        });
+        expect(response.ok).toBe(true);
+        const data = await response.json();
+        expect(data.status).toBe("ok");
+      } finally {
+        await cleanup();
+      }
+    },
+    timeoutMs
+  );
+});

examples/vercel/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/*.test.ts"
+  ]
+}