Sandbox Bindings

API reference for sandbox bindings — vercelSandbox(), localSandbox(), dockerSandbox() — and the SandboxInstance interface.

Sandbox bindings are passed to agent("my-agent", { sandbox: ... }) to configure where tools execute. Import them from experimental-agent/sandbox.

import { vercelSandbox, localSandbox, dockerSandbox } from "experimental-agent/sandbox";

const myAgent = agent("my-agent", {
  sandbox: vercelSandbox(),
});

When no sandbox is provided, the SDK auto-detects the best binding:

Vercel — if running on Vercel (VERCEL_OIDC_TOKEN is set)
Docker — if docker sandbox CLI is available
Local — fallback

You can also pass an array of bindings and select one at setup time via type:

const myAgent = agent("my-agent", {
  sandbox: [vercelSandbox(), localSandbox()],
});

const sb = myAgent.sandbox();
await sb.setup({ type: "vercel" });

vercelSandbox(defaults?)

import { vercelSandbox } from "experimental-agent/sandbox";

Vercel Sandbox with full Node.js and Python runtime, filesystem, and network.

Factory defaults

All binding factories accept optional defaults that are applied automatically during setup. Options passed to .setup() override these defaults.

Parameter	Type	Description
`version`	`string`	Setup version string for snapshot invalidation.
`run`	`(sandbox: SandboxInstance) => Promise<void>`	One-time setup function.
`config`	`VercelBindingConfig`	Binding-specific config (see below).
`networkPolicy`	`NetworkPolicy`	Network access rules.

const myAgent = agent("my-agent", {
  sandbox: vercelSandbox({
    version: "v1",
    run: async (sandbox) => {
      await sandbox.exec({ command: "npm", args: ["install"] });
    },
    config: { ports: [3000] },
  }),
});

VercelBindingConfig

Passed via config in the factory defaults or sandbox.setup({ config: { ... } }):

Parameter	Type	Default	Description
`cwd`	`string`	`"/home/vercel-sandbox"`	Working directory inside the sandbox.
`resources`	`{ vcpus: number }`	`{ vcpus: 2 }`	CPU resources.
`ports`	`number[]`	—	Ports to expose publicly.
`networkPolicy`	`NetworkPolicy`	—	Network access rules.
`snapshotId`	`string`	—	Resume from a specific snapshot.
`lifecycle`	`LifecycleConfig`	—	Lifecycle management settings.

LifecycleConfig:

Parameter	Type	Description
`pollIntervalMs`	`number`	Polling interval for status checks.
`stopAfterInactiveMs`	`number`	Stop sandbox after inactivity.
`snapshotBeforeTimeoutMs`	`number`	Snapshot before timeout.

NetworkPolicy: "allow-all" | "deny-all" | { allow?: string[]; subnets?: { allow?: string[]; deny?: string[] } }

"allow-all" — Full network access.
"deny-all" — No network access.
{ allow: string[] } — Allow specific domains (e.g. ["github.com", "*.github.com"]).
{ subnets: { allow?: string[]; deny?: string[] } } — Subnet-level rules.

const myAgent = agent("my-agent", {
  sandbox: vercelSandbox(),
});

const sb = myAgent.sandbox("my-sandbox");
await sb.setup({
  type: "vercel",
  version: "dev-env-v3",
  config: {
    ports: [3000],
    networkPolicy: { allow: ["github.com", "*.github.com"] },
  },
  run: async (sandbox) => {
    await sandbox.exec({ command: "npm", args: ["install"] });
  },
});

localSandbox(defaults?)

import { localSandbox } from "experimental-agent/sandbox";

Host filesystem sandbox. Tools execute directly on your machine. Great for development. Accepts the same factory defaults as vercelSandbox().

LocalBindingConfig

Parameter	Type	Default	Description
`cwd`	`string`	`process.cwd()`	Working directory.

const myAgent = agent("my-agent", {
  sandbox: localSandbox(),
});

dockerSandbox(defaults?)

import { dockerSandbox } from "experimental-agent/sandbox";

Docker container sandbox. Provides isolation without cloud dependencies. Requires Docker Desktop with Docker Sandboxes enabled. Accepts the same factory defaults as vercelSandbox().

DockerBindingConfig

Parameter	Type	Default	Description
`cwd`	`string`	`"/home/agent/workspace"`	Working directory inside the container.

const myAgent = agent("my-agent", {
  sandbox: dockerSandbox(),
});

SandboxInstance

The sandbox instance is available inside setup.run, and via ctx.sandbox in ToolContext.

sandbox.exec(opts)

Execute a shell command in the sandbox.

Parameter	Type	Required	Description
`command`	`string`	Yes	Command to run (e.g. `"npm"`, `"bash"`).
`args`	`string[]`	No	Command arguments.
`cwd`	`string`	No	Working directory for the command.
`env`	`Record<string, string>`	No	Environment variables.
`sudo`	`boolean`	No	Run as root.
`signal`	`AbortSignal`	No	AbortSignal to cancel the command.

Returns: Promise<ExecResult>

type ExecResult = {
  commandId: string;
  logs: () => AsyncIterable<{ stream: "stdout" | "stderr"; data: string }>;
  result: Promise<{ stdout: string; stderr: string; exitCode: number }>;
};

const result = await sandbox.exec({ command: "npm", args: ["run", "test"] });
const { stdout, stderr, exitCode } = await result.result;

sandbox.readFile(opts)

Read a file from the sandbox.

Parameter	Type	Description
`path`	`string`	Path relative to workspace root.
`signal`	`AbortSignal`	AbortSignal to cancel.

Returns: Promise<Buffer | null> — File contents, or null if not found.

sandbox.writeFiles(opts)

Write files to the sandbox.

Parameter	Type	Description
`files`	`UploadableFile[]`	Array of `{ path: string; content: string \| Buffer }`.
`destPath`	`string`	Destination directory.
`signal`	`AbortSignal`	AbortSignal to cancel.

Returns: Promise<void>

sandbox.getDomain(opts)

Get the public domain URL for an exposed port. Returns http://localhost:<port> for local and Docker sandboxes.

Parameter	Type	Description
`port`	`number`	Port number.
`signal`	`AbortSignal`	AbortSignal to cancel.

Returns: Promise<string>

sandbox.kill(opts)

Kill a running command.

Parameter	Type	Description
`commandId`	`string`	From `ExecResult.commandId`.
`signal`	`AbortSignal`	AbortSignal to cancel.

Returns: Promise<void>

sandbox.updateNetworkPolicy(opts)

Dynamically update network policy. Only supported on Vercel sandboxes.

Parameter	Type	Description
`policy`	`NetworkPolicy`	`"allow-all"`, `"deny-all"`, or `{ allow: string[] }`.
`signal`	`AbortSignal`	AbortSignal to cancel.

Returns: Promise<NetworkPolicy>

await sandbox.updateNetworkPolicy({ policy: { allow: ["github.com"] } });
await sandbox.updateNetworkPolicy({ policy: "deny-all" });