@tanstack/ai-sandbox weekly downloads statistics

@tanstack/ai-sandbox

Provider-agnostic sandbox layer for TanStack AI. Run coding-agent harness adapters (Grok Build, Claude Code, Codex, OpenCode, Gemini CLI) inside an isolated environment with a real filesystem, shell, and cloned repo — and stream their work back through chat().

Installation

Pick a provider package for where the sandbox runs:

| Package | Use when |

| @tanstack/ai-sandbox-local-process | Dev loop on your host (no isolation) | | @tanstack/ai-sandbox-docker | Isolated containers, snapshots, resume | | @tanstack/ai-sandbox-cloudflare | Cloudflare Workers + Containers | | @tanstack/ai-sandbox-vercel | Vercel Sandbox | | @tanstack/ai-sandbox-daytona | Daytona cloud sandboxes, snapshots | | @tanstack/ai-sandbox-upstash-box | Upstash Box cloud sandboxes, snapshots | | @tanstack/ai-sandbox-sprites | Sprites stateful sandboxes | | @tanstack/ai-sandbox-blaxel | Blaxel cloud sandboxes and previews | | @tanstack/ai-sandbox-boxd | boxd microVMs, live fork, snapshots | | @tanstack/ai-sandbox-e2b | E2B microVMs, snapshots and fork | | @tanstack/ai-sandbox-railway | Railway sandboxes, private networking |

Install the provider you select separately. For Blaxel:

Harness adapters are separate packages. The default path is Grok Build (@tanstack/ai-grok-build); others include @tanstack/ai-claude-code, @tanstack/ai-codex, and @tanstack/ai-opencode. All require withSandbox(...) middleware — chat() fails fast without it.

Three moving parts

| Part | What it is | How you configure it |

| Provider | Isolation primitive — host, container, cloud VM | dockerSandbox(), localProcessSandbox(), … | | Workspace | What the agent boots into — repo, setup, secrets, skills | defineWorkspace({ … }) | | Harness adapter | Which agent CLI runs and how output is translated | grokBuildText() (default), claudeCodeText(), codexText(), … |

defineSandbox() binds provider + workspace (+ optional policy, lifecycle, hooks). withSandbox(definition) is the chat() middleware that creates or resumes the sandbox for each run.

Core APIs

Workspace

Describe the working tree once, portably:

Skills and plugins are projected into each harness's native format at run time (.grok/config.toml, .mcp.json, .codex/config.toml, opencode.json, …). Bootstrap writes AGENTS.md and clones gitSkill repos; harness adapters handle the rest.

Policy

Guard what the agent may run:

Headless Grok Build and Codex stay on auto-approve when default is 'allow' and there is no ask list. Isolation is the outer sandbox (Docker, Daytona, and so on). Use Claude Code when you need command-level deny.

Claude Code can use an interactive policy:

Precedence is deny > ask > allow. Each harness adapter maps policy onto its native permission system (coarse flags for Grok Build/Codex; full interactive approval-requested on Claude Code). Provider-specific privilege and network rules live in the providers guide.

Lifecycle

Portable snapshots

Use portable snapshots when a later run must rebuild completed files after the provider sandbox is gone. Create one snapshots object, pass it to withPersistence and withSandbox, and put withPersistence first.

A successful terminal run saves regular files, empty directories, saved conversation data, and thread artifacts. Restore runs only in a new private sandbox. A live resumed sandbox keeps its current files. Read Keep Files After Reload for the full server setup.

Secrets

Use createSecrets() so values stay behind opaque SecretRef tokens. They are never written to snapshots, the sandbox store, or event logs. The sandbox layer resolves them onto the live handle at create, resume, and snapshot restore:

Host tool bridge

chat() server tools can be bridged into the in-sandbox agent over MCP. The agent calls mcptanstack; execution runs back on the host where your closures, DB, and secrets live.

Run flow

Subpath exports

| Import | Purpose |

| @tanstack/ai-sandbox | Core sandbox APIs | | @tanstack/ai-sandbox/ngrok | Optional ngrok tunnel helper for remote tool bridging |

Documentation

Full guides on tanstack.com/ai:

• Quick Start — Grok Build in Docker • Providers • Workspace • Provisioning (skills, MCP, plugins) • Policy • Tools (host tool bridge) • Lifecycle & snapshots • Portable sandbox snapshots • Pick which files to keep

Examples

| Example | What it demonstrates |

| examples/sandbox-web | Build-and-preview with harness × provider matrix (Grok default in UI) | | examples/sandbox-cloudflare | Edge deploy with live preview URL |

When to use a sandbox

Use a sandbox when the agent needs to act on a real codebase — run commands, edit files, clone repos, start dev servers. For read-only Q&A over code you already have in context, a normal chat() with server tools is enough.

Persistence (durable SandboxStore / LockStore, event-log replay) is out of scope for v1 but every seam is persistence-ready via optional capabilities.

Description from the npm listing.