SDK sandbox provisioning: built-in providers, docs restructure, and quickstart overhaul

- Add built-in sandbox providers (local, docker, e2b, daytona, vercel, cloudflare) to the TypeScript SDK so users import directly instead of passing client instances
- Restructure docs: rename architecture to orchestration-architecture, add new architecture page for server overview, improve getting started flow
- Rewrite quickstart to be TypeScript-first with provider CodeGroup and custom provider accordion
- Update all examples to use new provider APIs
- Update persist drivers and foundry for new SDK surface

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

examples/boxlite/src/index.ts

@@ -25,7 +25,7 @@ const baseUrl = "http://localhost:3000";
 
 console.log("Connecting to server...");
 const client = await SandboxAgent.connect({ baseUrl });
-const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root", mcpServers: [] } });
+const session = await client.createSession({ agent: detectAgent(), cwd: "/root" });
 const sessionId = session.id;
 
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);

examples/computesdk/src/computesdk.ts

@@ -131,7 +131,7 @@ export async function runComputeSdkExample(): Promise<void> {
   process.once("SIGTERM", handleExit);
 
   const client = await SandboxAgent.connect({ baseUrl });
-  const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/home", mcpServers: [] } });
+  const session = await client.createSession({ agent: detectAgent(), cwd: "/home" });
   const sessionId = session.id;
 
   console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);

examples/daytona/src/index.ts

@@ -1,42 +1,31 @@
-import { Daytona } from "@daytonaio/sdk";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
-
-const daytona = new Daytona();
+import { daytona } from "sandbox-agent/daytona";
+import { detectAgent } from "@sandbox-agent/example-shared";
 
 const envVars: Record<string, string> = {};
 if (process.env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 if (process.env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
 
-// Use default image and install sandbox-agent at runtime (faster startup, no snapshot build)
-console.log("Creating Daytona sandbox...");
-const sandbox = await daytona.create({ envVars, autoStopInterval: 0 });
+const client = await SandboxAgent.start({
+  sandbox: daytona({
+    create: { envVars },
+  }),
+});
 
-// Install sandbox-agent and start server
-console.log("Installing sandbox-agent...");
-await sandbox.process.executeCommand("curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh");
+console.log(`UI: ${client.inspectorUrl}`);
 
-console.log("Installing agents...");
-await sandbox.process.executeCommand("sandbox-agent install-agent claude");
-await sandbox.process.executeCommand("sandbox-agent install-agent codex");
+const session = await client.createSession({
+  agent: detectAgent(),
+  cwd: "/home/daytona",
+});
 
-await sandbox.process.executeCommand("nohup sandbox-agent server --no-token --host 0.0.0.0 --port 3000 >/tmp/sandbox-agent.log 2>&1 &");
+session.onEvent((event) => {
+  console.log(`[${event.sender}]`, JSON.stringify(event.payload));
+});
 
-const baseUrl = (await sandbox.getSignedPreviewUrl(3000, 4 * 60 * 60)).url;
+session.prompt([{ type: "text", text: "Say hello from Daytona in one sentence." }]);
 
-console.log("Connecting to server...");
-const client = await SandboxAgent.connect({ baseUrl });
-const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/home/daytona", mcpServers: [] } });
-const sessionId = session.id;
-
-console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
-console.log("  Press Ctrl+C to stop.");
-
-const keepAlive = setInterval(() => {}, 60_000);
-const cleanup = async () => {
-  clearInterval(keepAlive);
-  await sandbox.delete(60);
+process.once("SIGINT", async () => {
+  await client.destroySandbox();
   process.exit(0);
-};
-process.once("SIGINT", cleanup);
-process.once("SIGTERM", cleanup);
+});

examples/docker/package.json

@@ -9,10 +9,10 @@
   "dependencies": {
     "@sandbox-agent/example-shared": "workspace:*",
     "dockerode": "latest",
+    "get-port": "latest",
     "sandbox-agent": "workspace:*"
   },
   "devDependencies": {
-    "@types/dockerode": "latest",
     "@types/node": "latest",
     "tsx": "latest",
     "typescript": "latest",

examples/docker/src/index.ts

@@ -1,68 +1,40 @@
-import Docker from "dockerode";
 import fs from "node:fs";
 import path from "node:path";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
+import { docker } from "sandbox-agent/docker";
+import { detectAgent } from "@sandbox-agent/example-shared";
 import { FULL_IMAGE } from "@sandbox-agent/example-shared/docker";
 
-const IMAGE = FULL_IMAGE;
-const PORT = 3000;
-const agent = detectAgent();
 const codexAuthPath = process.env.HOME ? path.join(process.env.HOME, ".codex", "auth.json") : null;
 const bindMounts = codexAuthPath && fs.existsSync(codexAuthPath) ? [`${codexAuthPath}:/home/sandbox/.codex/auth.json:ro`] : [];
+const env = [
+  process.env.ANTHROPIC_API_KEY ? `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}` : "",
+  process.env.OPENAI_API_KEY ? `OPENAI_API_KEY=${process.env.OPENAI_API_KEY}` : "",
+  process.env.CODEX_API_KEY ? `CODEX_API_KEY=${process.env.CODEX_API_KEY}` : "",
+].filter(Boolean);
 
-const docker = new Docker({ socketPath: "/var/run/docker.sock" });
-
-// Pull image if needed
-try {
-  await docker.getImage(IMAGE).inspect();
-} catch {
-  console.log(`Pulling ${IMAGE}...`);
-  await new Promise<void>((resolve, reject) => {
-    docker.pull(IMAGE, (err: Error | null, stream: NodeJS.ReadableStream) => {
-      if (err) return reject(err);
-      docker.modem.followProgress(stream, (err: Error | null) => (err ? reject(err) : resolve()));
-    });
-  });
-}
-
-console.log("Starting container...");
-const container = await docker.createContainer({
-  Image: IMAGE,
-  Cmd: ["server", "--no-token", "--host", "0.0.0.0", "--port", `${PORT}`],
-  Env: [
-    process.env.ANTHROPIC_API_KEY ? `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}` : "",
-    process.env.OPENAI_API_KEY ? `OPENAI_API_KEY=${process.env.OPENAI_API_KEY}` : "",
-    process.env.CODEX_API_KEY ? `CODEX_API_KEY=${process.env.CODEX_API_KEY}` : "",
-  ].filter(Boolean),
-  ExposedPorts: { [`${PORT}/tcp`]: {} },
-  HostConfig: {
-    AutoRemove: true,
-    PortBindings: { [`${PORT}/tcp`]: [{ HostPort: `${PORT}` }] },
-    Binds: bindMounts,
-  },
+const client = await SandboxAgent.start({
+  sandbox: docker({
+    image: FULL_IMAGE,
+    env,
+    binds: bindMounts,
+  }),
 });
-await container.start();
 
-const baseUrl = `http://127.0.0.1:${PORT}`;
+console.log(`UI: ${client.inspectorUrl}`);
 
-const client = await SandboxAgent.connect({ baseUrl });
-const session = await client.createSession({ agent, sessionInit: { cwd: "/home/sandbox", mcpServers: [] } });
-const sessionId = session.id;
+const session = await client.createSession({
+  agent: detectAgent(),
+  cwd: "/home/sandbox",
+});
 
-console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
-console.log("  Press Ctrl+C to stop.");
+session.onEvent((event) => {
+  console.log(`[${event.sender}]`, JSON.stringify(event.payload));
+});
 
-const keepAlive = setInterval(() => {}, 60_000);
-const cleanup = async () => {
-  clearInterval(keepAlive);
-  try {
-    await container.stop({ t: 5 });
-  } catch {}
-  try {
-    await container.remove({ force: true });
-  } catch {}
+session.prompt([{ type: "text", text: "Say hello from Docker in one sentence." }]);
+
+process.once("SIGINT", async () => {
+  await client.destroySandbox();
   process.exit(0);
-};
-process.once("SIGINT", cleanup);
-process.once("SIGTERM", cleanup);
+});

examples/e2b/src/index.ts

@@ -1,45 +1,31 @@
-import { Sandbox } from "@e2b/code-interpreter";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
+import { e2b } from "sandbox-agent/e2b";
+import { detectAgent } from "@sandbox-agent/example-shared";
 
 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;
 
-console.log("Creating E2B sandbox...");
-const sandbox = await Sandbox.create({ allowInternetAccess: true, envs });
+const client = await SandboxAgent.start({
+  sandbox: e2b({
+    create: { envs },
+  }),
+});
 
-const run = async (cmd: string) => {
-  const result = await sandbox.commands.run(cmd);
-  if (result.exitCode !== 0) throw new Error(`Command failed: ${cmd}\n${result.stderr}`);
-  return result;
-};
+console.log(`UI: ${client.inspectorUrl}`);
 
-console.log("Installing sandbox-agent...");
-await run("curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh");
+const session = await client.createSession({
+  agent: detectAgent(),
+  cwd: "/home/user",
+});
 
-console.log("Installing agents...");
-await run("sandbox-agent install-agent claude");
-await run("sandbox-agent install-agent codex");
+session.onEvent((event) => {
+  console.log(`[${event.sender}]`, JSON.stringify(event.payload));
+});
 
-console.log("Starting server...");
-await sandbox.commands.run("sandbox-agent server --no-token --host 0.0.0.0 --port 3000", { background: true, timeoutMs: 0 });
+session.prompt([{ type: "text", text: "Say hello from E2B in one sentence." }]);
 
-const baseUrl = `https://${sandbox.getHost(3000)}`;
-
-console.log("Connecting to server...");
-const client = await SandboxAgent.connect({ baseUrl });
-const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/home/user", mcpServers: [] } });
-const sessionId = session.id;
-
-console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
-console.log("  Press Ctrl+C to stop.");
-
-const keepAlive = setInterval(() => {}, 60_000);
-const cleanup = async () => {
-  clearInterval(keepAlive);
-  await sandbox.kill();
+process.once("SIGINT", async () => {
+  await client.destroySandbox();
   process.exit(0);
-};
-process.once("SIGINT", cleanup);
-process.once("SIGTERM", cleanup);
+});

examples/file-system/src/index.ts

@@ -44,7 +44,7 @@ const readmeText = new TextDecoder().decode(readmeBytes);
 console.log(`  README.md content: ${readmeText.trim()}`);
 
 console.log("Creating session...");
-const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/opt/my-project", mcpServers: [] } });
+const session = await client.createSession({ agent: detectAgent(), cwd: "/opt/my-project" });
 const sessionId = session.id;
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log('  Try: "read the README in /opt/my-project"');

examples/permissions/src/index.ts

@@ -2,6 +2,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { Command } from "commander";
 import { SandboxAgent, type PermissionReply, type SessionPermissionRequest } from "sandbox-agent";
+import { local } from "sandbox-agent/local";
 
 const options = parseOptions();
 const agent = options.agent.trim().toLowerCase();
@@ -9,10 +10,7 @@ const autoReply = parsePermissionReply(options.reply);
 const promptText = options.prompt?.trim() || `Create ./permission-example.txt with the text 'hello from the ${agent} permissions example'.`;
 
 const sdk = await SandboxAgent.start({
-  spawn: {
-    enabled: true,
-    log: "inherit",
-  },
+  sandbox: local({ log: "inherit" }),
 });
 
 try {
@@ -43,10 +41,7 @@ try {
   const session = await sdk.createSession({
     agent,
     ...(mode ? { mode } : {}),
-    sessionInit: {
-      cwd: process.cwd(),
-      mcpServers: [],
-    },
+    cwd: process.cwd(),
   });
 
   const rl = autoReply

examples/skills-custom-tool/src/index.ts

@@ -36,7 +36,7 @@ await client.setSkillsConfig({ directory: "/", skillName: "random-number" }, { s
 
 // Create a session.
 console.log("Creating session with custom skill...");
-const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root", mcpServers: [] } });
+const session = await client.createSession({ agent: detectAgent(), cwd: "/root" });
 const sessionId = session.id;
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log('  Try: "generate a random number between 1 and 100"');

examples/skills/src/index.ts

@@ -15,7 +15,7 @@ await client.setSkillsConfig(
 );
 
 console.log("Creating session...");
-const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/root", mcpServers: [] } });
+const session = await client.createSession({ agent: detectAgent(), cwd: "/root" });
 const sessionId = session.id;
 console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
 console.log('  Try: "How do I start sandbox-agent?"');

examples/vercel/src/index.ts

@@ -1,56 +1,34 @@
-import { Sandbox } from "@vercel/sandbox";
 import { SandboxAgent } from "sandbox-agent";
-import { detectAgent, buildInspectorUrl } from "@sandbox-agent/example-shared";
+import { vercel } from "sandbox-agent/vercel";
+import { detectAgent } from "@sandbox-agent/example-shared";
 
-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;
+const env: Record<string, string> = {};
+if (process.env.ANTHROPIC_API_KEY) env.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
+if (process.env.OPENAI_API_KEY) env.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
 
-console.log("Creating Vercel sandbox...");
-const sandbox = await Sandbox.create({
-  runtime: "node24",
-  ports: [3000],
+const client = await SandboxAgent.start({
+  sandbox: vercel({
+    create: {
+      runtime: "node24",
+      env,
+    },
+  }),
 });
 
-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(`UI: ${client.inspectorUrl}`);
 
-console.log("Installing sandbox-agent...");
-await run("sh", ["-c", "curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/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 session = await client.createSession({
+  agent: detectAgent(),
+  cwd: "/home/vercel-sandbox",
 });
 
-const baseUrl = sandbox.domain(3000);
+session.onEvent((event) => {
+  console.log(`[${event.sender}]`, JSON.stringify(event.payload));
+});
 
-console.log("Connecting to server...");
-const client = await SandboxAgent.connect({ baseUrl });
-const session = await client.createSession({ agent: detectAgent(), sessionInit: { cwd: "/home/vercel-sandbox", mcpServers: [] } });
-const sessionId = session.id;
+session.prompt([{ type: "text", text: "Say hello from Vercel in one sentence." }]);
 
-console.log(`  UI: ${buildInspectorUrl({ baseUrl, sessionId })}`);
-console.log("  Press Ctrl+C to stop.");
-
-const keepAlive = setInterval(() => {}, 60_000);
-const cleanup = async () => {
-  clearInterval(keepAlive);
-  await sandbox.stop();
+process.once("SIGINT", async () => {
+  await client.destroySandbox();
   process.exit(0);
-};
-process.once("SIGINT", cleanup);
-process.once("SIGTERM", cleanup);
+});