Skip to main content
The TypeScript SDK is centered on sandbox-agent and its SandboxAgent class.

​
Install

npm install [email protected]

​
Optional React components

npm install @sandbox-agent/[email protected]

​
Create a client

import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});
SandboxAgent.connect(...) now waits for /v1/health by default before other SDK requests proceed. To disable that gate, pass waitForHealth: false. To keep the default gate but fail after a bounded wait, pass waitForHealth: { timeoutMs: 120_000 }. To cancel the startup wait early, pass signal: abortController.signal. With a custom fetch handler (for example, proxying requests inside Workers): 
const sdk = await SandboxAgent.connect({
  fetch: (input, init) => customFetch(input, init),
});
With an abort signal for the startup health gate: 
const controller = new AbortController();

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  signal: controller.signal,
});

controller.abort();
With persistence (see Persisting Sessions for driver options): 
import { SandboxAgent, InMemorySessionPersistDriver } from "sandbox-agent";

const persist = new InMemorySessionPersistDriver();

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  persist,
});
Local spawn with a sandbox provider: 
import { SandboxAgent } from "sandbox-agent";
import { local } from "sandbox-agent/local";

const sdk = await SandboxAgent.start({
  sandbox: local(),
});

// sdk.sandboxId — prefixed provider ID (e.g. "local/127.0.0.1:2468")

await sdk.destroySandbox(); // provider-defined cleanup + disposes client
SandboxAgent.start(...) requires a sandbox provider. Built-in providers:
ImportProvider
sandbox-agent/localLocal subprocess
sandbox-agent/dockerDocker container
sandbox-agent/e2bE2B sandbox
sandbox-agent/daytonaDaytona workspace
sandbox-agent/vercelVercel Sandbox
sandbox-agent/cloudflareCloudflare Sandbox
Use sdk.dispose() to disconnect without changing sandbox state, sdk.pauseSandbox() for graceful suspension when supported, or sdk.killSandbox() for permanent deletion.

​
Session flow

const session = await sdk.createSession({
  agent: "mock",
  cwd: "/",
});

const prompt = await session.prompt([
  { type: "text", text: "Summarize this repository." },
]);

console.log(prompt.stopReason);
Load and destroy: 
const restored = await sdk.resumeSession(session.id);
await restored.prompt([{ type: "text", text: "Continue from previous context." }]);

await sdk.destroySession(restored.id);

​
Session configuration

Set model, mode, or thought level at creation or on an existing session: 
const session = await sdk.createSession({
  agent: "codex",
  model: "gpt-5.3-codex",
});

await session.setModel("gpt-5.2-codex");
await session.setMode("auto");

const options = await session.getConfigOptions();
const modes = await session.getModes();
Handle permission requests from agents that ask before executing tools: 
const claude = await sdk.createSession({
  agent: "claude",
  mode: "default",
});

claude.onPermissionRequest((request) => {
  void claude.respondPermission(request.id, "once");
});
See Agent Sessions for full details on config options and error handling.

​
Events

Subscribe to live events: 
const unsubscribe = session.onEvent((event) => {
  console.log(event.eventIndex, event.sender, event.payload);
});

await session.prompt([{ type: "text", text: "Give me a short summary." }]);
unsubscribe();
Fetch persisted events: 
const page = await sdk.getEvents({
  sessionId: session.id,
  limit: 100,
});

console.log(page.items.length);

​
Control-plane and HTTP helpers

const health = await sdk.getHealth();
const agents = await sdk.listAgents();
await sdk.installAgent("codex", { reinstall: true });

const entries = await sdk.listFsEntries({ path: "." });
const writeResult = await sdk.writeFsFile({ path: "./hello.txt" }, "hello");

console.log(health.status, agents.agents.length, entries.length, writeResult.path);

​
Desktop API

The SDK also wraps the desktop host/runtime HTTP API. Install desktop dependencies first on Linux hosts: 
sandbox-agent install desktop --yes
Then query status, surface remediation if needed, and start the runtime: 
const status = await sdk.getDesktopStatus();

if (status.state === "install_required") {
  console.log(status.installCommand);
}

const started = await sdk.startDesktop({
  width: 1440,
  height: 900,
  dpi: 96,
});

const screenshot = await sdk.takeDesktopScreenshot();
const displayInfo = await sdk.getDesktopDisplayInfo();

await sdk.moveDesktopMouse({ x: 400, y: 300 });
await sdk.clickDesktop({ x: 400, y: 300, button: "left", clickCount: 1 });
await sdk.typeDesktopText({ text: "hello world", delayMs: 10 });
await sdk.pressDesktopKey({ key: "ctrl+l" });

await sdk.stopDesktop();
Screenshot helpers return Uint8Array PNG bytes. The SDK does not attempt to install OS packages remotely; callers should surface missingDependencies and installCommand from getDesktopStatus().

​
Error handling

import { SandboxAgentError } from "sandbox-agent";

try {
  await sdk.listAgents();
} catch (error) {
  if (error instanceof SandboxAgentError) {
    console.error(error.status, error.problem);
  }
}

​
Inspector URL

import { buildInspectorUrl } from "sandbox-agent";

const url = buildInspectorUrl({
  baseUrl: "https://your-sandbox-agent.example.com",
  headers: { "X-Custom-Header": "value" },
});

console.log(url);
Parameters:
  • baseUrl (required unless fetch is provided): Sandbox Agent server URL
  • token (optional): Bearer token for authenticated servers
  • headers (optional): Additional request headers
  • fetch (optional): Custom fetch implementation used by SDK HTTP and session calls
  • skipHealthCheck (optional): set true to skip the startup /v1/health wait
  • waitForHealth (optional, defaults to enabled): waits for /v1/health before HTTP helpers and session setup proceed; pass false to disable or { timeoutMs } to bound the wait
  • signal (optional): aborts the startup /v1/health wait used by connect()

​
LLM credentials

Sandbox Agent supports personal API keys, shared organization keys, and per-tenant gateway keys with budget enforcement. See LLM Credentials for setup details.