API Reference

This page describes the public surface of @inbrowser/sandbox.

Import Paths

Related guides:

• How to wire a sandbox into an agent
• How to manage checkpoint history
• Why sandbox tools and agent tools are separate

createSandbox

function createSandbox(options: CreateSandboxOptions): Sandbox;

CreateSandboxOptions:

Sandbox:

createWorkspaceSandbox

function createWorkspaceSandbox(options: CreateWorkspaceSandboxOptions): Promise<Sandbox>;

Adapts a BrowserWorkspace from @inbrowser/workspace into a sandbox. The adapter creates a workspace shell, git service, package service, and optional preview service, then passes them to createSandbox.

standardSandboxTools

function standardSandboxTools(): readonly SandboxTool[];

Returns the standard sandbox tool definitions. createWorkspaceSandbox installs these tools by default. Low-level createSandbox callers can pass them with tools: standardSandboxTools().

sandbox.tools:

Standard tools:

sandbox.checkpoints

create accepts either a label string or metadata:

const checkpoint = await sandbox.checkpoints.create({
  label: 'before write',
  turnId: 'turn-1',
  toolCallId: 'tool-1',
  reason: 'before-tool',
  summary: 'Before editing src/App.tsx',
  metadata: { file: 'src/App.tsx' },
});

Checkpoint records include id, createdAt, snapshot, and optional label, parentId, turnId, messageId, toolCallId, reason, summary, and metadata.

Reasons are:

'manual' | 'before-turn' | 'before-tool' | 'after-turn' | 'restore'

Restore options:

await sandbox.checkpoints.restore(checkpoint.id, {
  mode: 'replace-current',
  recordEvent: true,
});

Pruning keeps automatic checkpoint history bounded:

sandbox.checkpoints.prune({
  reason: 'before-tool',
  keepLatest: 20,
});

createRuntimeAdapter

function createRuntimeAdapter(run: SandboxRuntime['run']): SandboxRuntime;

Wraps a command-run function in the SandboxRuntime shape. Use this when a host already has a command runner and only needs to adapt it into a sandbox.

Remote Bridge

@inbrowser/sandbox/remote exports the browser-safe bridge surface for running a sandbox against a host-side container or VM process.

import {
  createRemoteSandbox,
  createWebSocketBridgeProvider,
} from '@inbrowser/sandbox/remote';

const sandbox = await createRemoteSandbox({
  id: 'local-container-session',
  transport: createWebSocketBridgeProvider({
    url: 'ws://127.0.0.1:8790/bridge',
    token: '<bridge-token-from-/bridge-config>',
  }),
});

The bridge separates transport from runtime:

Remote sandbox requests use REMOTE_PROTOCOL_TYPES, including host.status, session.create, fs.read, fs.write, fs.list, run.start, run.cancel, port.expose, checkpoint.create, and checkpoint.restore. Host stream envelopes can carry file events, sandbox events, port metadata, and artifact metadata. createRemoteSandbox re-emits remote artifacts and ports as normal SandboxEvent values.

Host-side bridge code can use the decision-less host API:

import { startRemoteContainerBridge } from '@inbrowser/sandbox/remote/host';

const bridge = await startRemoteContainerBridge({
  image: 'ubuntu:latest',
});

const sandbox = await createRemoteSandbox({
  id: 'local-container-session',
  transport: bridge.createWebSocketProvider(),
});

The default resolver chooses Bun under Bun, Node under Node, and Apple container when the CLI is available on macOS. Explicit composition remains available when an app wants to choose every layer:

import { createAppleContainerProvider } from '@inbrowser/sandbox/remote/apple-container';
import { startNodeBridgeHostServer } from '@inbrowser/sandbox/remote/node';

const server = await startNodeBridgeHostServer({
  provider: createAppleContainerProvider({
    image: 'ubuntu:latest',
  }),
  port: 8790,
});

console.log(server.bridgeOrigin);

The provider contract exported from @inbrowser/sandbox/remote/host is runtime specific and intentionally separate from BridgeTransportProvider. A WebSocket, Realtime Database, or test transport can drive the same Apple, WSL, Docker, or fake container provider without changing the sandbox client API.

Events

SandboxEvent variants:

All events include sandboxId and timestamp.

Agent Bridge

@inbrowser/agent/sandbox exports:

function createSandboxAgentTools(
  sandbox: Sandbox;
  options?: { names?: readonly string[] };
): SandboxAgentTools;

The bridge returns an AgentTools object built from the sandbox’s installed tools. Pass names to expose only selected tools. Pure sandbox tools are marked parallelSafe.