ai-sandbox

name ai-sandbox description Run harness adapters (Claude Code, Codex, OpenCode) INSIDE isolated sandboxes via defineSandbox + withSandbox + a provider (localProcessSandbox / dockerSandbox). Covers declarative provisioning: createSecrets + secret/bearer, skills (agentSkill/gitSkill/mcpSkill/ fileSkill), plugins, instructions → canonical AGENTS.md + symlinks projected per harness; shallow-clone default with depth opt-out; serial/parallel setup callback over a persistent shell; snapshot-after-setup default with snapshotMaxAge TTL. It also covers portable snapshots after a successful terminal run with withPersistence before withSandbox and memorySandboxSnapshots for local examples. It covers named saves with snapshots.save, selected-checkpoint forks with snapshots.fork, and authorized artifact reads with snapshots.readArtifact. See docs/sandbox/portable-snapshots.md. It covers defineWorkspace (git/setup/scripts/skills/secrets/ instructions/plugins), defineSandboxPolicy (allow/ask/deny), lifecycle/resume, the SandboxHandle (fs/git/process/ports), capability tokens, defineSandbox hooks (onFile/onFileCreate/onFileChange/onFileDelete/onReady/onError/ onDestroy) + fileEvents flag, chat middleware sandbox group (defineChatMiddleware sandbox hooks), the sandbox debug category, watchWorkspace as a low-level building block, the file.changed / sandbox.file / claude-code.session-id events, and the run journal (spawnNdjson journal option, runId uniqueness, follow vs bounded-poll reading, alignToStoredLog replay alignment, chunkFingerprint, createRunScopedIdGen), and takeover of detached runs (withSandbox runs+durability as one opt-in, detach vs cancel via requestRunCancel / RUN_CANCEL_REASON, sandboxRunDriver on the resume path, single-writer fencing of BOTH the event log and the run record, replay-from-zero with JournalReplayDivergedError, the distributed LockStore requirement). Use whenever a harness adapter needs a sandbox or when building sandbox providers. type sub-skill library tanstack-ai library_version 0.2.4 sources ["TanStack/ai:docs/sandbox/overview.md","TanStack/ai:docs/sandbox/takeover.md","TanStack/ai:docs/sandbox/reaping.md"] Sandboxes Harness adapters declare requires: [SandboxCapability] . chat() errors unless some middleware provides it — withSandbox(...) does. The adapter then runs the agent CLI inside the sandbox and streams its events back. Setup — Claude Code in a Docker sandbox import { chat, toServerSentEventsResponse } from '@tanstack/ai' import { claudeCodeText } from '@tanstack/ai-claude-code' import { createSecrets, defineSandbox, defineWorkspace, withSandbox, } from '@tanstack/ai-sandbox' import { dockerSandbox } from '@tanstack/ai-sandbox-docker' const sandbox = defineSandbox ({ id : 'repo-agent' , provider : dockerSandbox ({ image : 'node:22' }), workspace : defineWorkspace ({ source : { type : 'git' , url : 'https://github.com/owner/repo' , ref : 'main' }, packageManager : 'pnpm' , setup : [ 'corepack enable' , 'pnpm install' ], scripts : { test : 'pnpm test' }, secrets : createSecrets ({ ANTHROPIC_API_KEY : process. env . ANTHROPIC_API_KEY ?? '' , }), }), lifecycle : { reuse : 'thread' , snapshot : 'after-setup' , keepAlive : '30m' }, }) export async function POST ( request : Request ) { const { threadId, messages } = await request. json () const stream = chat ({ threadId, adapter : claudeCodeText ( 'sonnet' ), messages, middleware : [ withSandbox (sandbox)], }) return toServerSentEventsResponse (stream) } Type-safe secrets import { createSecrets, bearer } from '@tanstack/ai-sandbox' const secrets = createSecrets ({ GH : process. env . GH_TOKEN ?? '' , SENTRY : process. env . SENTRY_TOKEN ?? '' , }) // secrets.GH is a SecretRef — the underlying string is stored in a // non-enumerable symbol-keyed registry and never logged, snapshotted, // or written to the sandbox store. Pass secrets to defineWorkspace({ secrets }) so skill and MCP projectors can resolve them. Use secret: secrets.GH in gitSkill for private-repo auth and secrets.GH / bearer(secrets.GH) in MCP header values: secrets.GH — resolves to the raw token value. bearer(secrets.GH) — resolves to "Bearer <value>" . Declarative provisioning (skills, plugins, MCP, instructions) import { agentSkill, gitSkill, mcpSkill, fileSkill, bearer, createSecrets, defineWorkspace, } from '@tanstack/ai-sandbox' const secrets = createSecrets ({ GH : process. env . GH_TOKEN ?? '' }) defineWorkspace ({ source : { type : 'git' , url : 'https://github.com/owner/repo' }, secrets, skills : [ agentSkill ( 'tanstack' ), // named skill (no-op with warning on CLIs that lack the concept) gitSkill ({ repo : 'owner/private-skills' , secret : secrets. GH , // resolved at bootstrap time, never stored // into: '/abs/path/inside/sandbox' // optional; defaults to .tanstack-skills/<repo> }), mcpSkill ( 'my-mcp' , { url : 'https://mcp.example.com' , headers : { Authorization : bearer (secrets. GH ) }, }), fileSkill ({ path : '.hints.md' , content : 'Prefer pnpm.' }), ], plugins : [ '@anthropic/plugin-foo' ], // no-op with warning on CLIs without a plugin concept instructions : 'Always run `pnpm test` before proposing a change.' , }) Each skill type is projected per harness (Claude Code → .mcp.json ; Codex → .codex/config.toml ; OpenCode → opencode.json ). instructions is written as AGENTS.md at the workspace root; CLAUDE.md and GEMINI.md are created as symlinks (falling back to copies on symlink failure). Skills/plugins that a CLI lacks emit a console.warn and are skipped. gitSkill into field: an absolute path inside the sandbox where the repo is cloned. Defaults to <root>/.tanstack-skills/<repo-basename> . Fast init Shallow clone ( depth ) githubRepo / gitSource default to --depth 1 --single-branch . Override: import { githubRepo, defineWorkspace } from '@tanstack/ai-sandbox' defineWorkspace ({ source : githubRepo ({ repo : 'owner/app' }) }) // depth 1 (default) defineWorkspace ({ source : githubRepo ({ repo : 'owner/app' , depth : 10 }) }) // 10 commits defineWorkspace ({ source : githubRepo ({ repo : 'owner/app' , depth : 'full' }) }) // full history Serial / parallel setup callback setup accepts a plain Array<string> (all serial) or a callback that records serial and parallel groups over a persistent shell whose cwd/env carry over between serial steps: import { githubRepo, defineWorkspace } from '@tanstack/ai-sandbox' defineWorkspace ({ source : githubRepo ({ repo : 'owner/app' }), setup : ( { serial, parallel } ) => { serial ( 'corepack enable' ) serial ( 'pnpm install' ) parallel ([ 'pnpm build' , 'pnpm typecheck' ]) // concurrent; inherit cwd+env from shell serial ( 'echo done' ) }, }) Snapshot-after-setup and snapshotMaxAge When the provider supports snapshots, bootstrap takes one automatically after setup completes. Subsequent runs resume from the snapshot (skipping setup). Override or add a TTL: import { defineSandbox } from '@tanstack/ai-sandbox' import { dockerSandbox } from '@tanstack/ai-sandbox-docker' const sandbox = defineSandbox ({ id : 'repo-agent' , provider : dockerSandbox ({ image : 'node:22' }), lifecycle : { snapshot : 'after-setup' , // default when provider.capabilities().snapshots snapshotMaxAge : '24h' , // re-create when the snapshot is older than this }, }) Providers without snapshot support skip the step silently. Portable sandbox snapshots Portable snapshots keep completed workspace files in application persistence. They are separate from provider-native bootstrap snapshots. Configure the middleware in this order, with the same persistence value in both places: import { withPersistence } from '@tanstack/ai-persistence' import { InMemorySandboxInstanceStore , memorySandboxSnapshots, withSandbox, } from '@tanstack/ai-sandbox' // Your `defineSandbox(...)` result. import { sandbox } from './sandbox' const instances = new InMemorySandboxInstanceStore () const snapshots = await memorySandboxSnapshots ({ sandbox, instances }) const middleware = [ withPersistence (snapshots. persistence ), withSandbox (sandbox, { instances, snapshots }), ] Each successful terminal run saves regular files, empty directories, durable conversation data, and persisted thread artifacts. A later run restores the latest checkpoint only into a new private sandbox. A live resumed sandbox is never overwritten. The default policy excludes .git , node_modules , and .env* path segments at every depth. It excludes the exact projection marker only at the workspace root. It also excludes root CLAUDE.md and GEMINI.md , plus direct .claude/skills/<name> , .codex/skills/<name> , and .grok/skills/<name> paths. These exclusions use paths even for regular files or copies. If you pass only include or only redact , the default exclusions stay in place. If you pass exclude , that function replaces the default exclusions, except for exact projection-marker protection. Copy defaultSandboxSnapshotPolicy() first when you write exclude . Pass include and exclude functions on policy to store only some files, including one file. There is no save({ files }) list. See docs/sandbox/portable-snapshots-files.md . Resolved secrets are redacted before the data is stored. Symlinks, executables, and special filesystem entries fail the capture or restore. Each thread has one writer lease. Pause and detach release the lease without a partial checkpoint. Blob retention is manual because there is no automatic garbage collection yet. Read these pages for the server-only setup: docs/sandbox/portable-snapshots.md docs/sandbox/portable-snapshots-configure.md docs/sandbox/portable-snapshots-save.md docs/sandbox/portable-snapshots-fork.md docs/sandbox/portable-snapshots-artifacts.md docs/sandbox/portable-snapshots-tools.md docs/sandbox/portable-snapshots-files.md docs/sandbox/portable-snapshots-safety.md For a user-marked workspace state, call snapshots.save on the server. Bind sandbox and instances at create time, or pass them on save . The call needs threadId , runId , and a label. It requires a live reusable sandbox. reuse: 'none' cannot save a named checkpoint. To branch from a selected checkpoint, call snapshots.fork with the thread id, checkpoint id, and destination thread id. The store must implement atomic forkFromCheckpoint . The destination thread must be empty. A fork copies the selected snapshot, not the latest snapshot. To send a checkpoint artifact, call snapshots.readArtifact on the server. First authorize the caller for the supplied thread. The method makes sure that the checkpoint belongs to that thread, then returns its metadata and bytes. It does not authorize a caller or create an HTTP response. For a SQLite checkpoint store, use one transaction for a checkpoint write, its head update, and every blob reference update. Use one transaction for a fork, including its copied conversation. A partial transaction breaks snapshot consistency. Snapshot capture supports regular files and empty directories only. It excludes .git , node_modules , and .env* path segments at every depth. It excludes the exact projection marker only at the workspace root. It also excludes root CLAUDE.md and GEMINI.md , plus direct .claude/skills/<name> , .codex/skills/<name> , and .grok/skills/<name> paths. These exclusions use paths even for regular files or copies. If you pass only include or only redact , the default exclusions stay in place. If you pass exclude , that function replaces the default exclusions, except for exact projection-marker protection. It rejects symlinks, executable files, and special filesystem entries. Restore verifies the manifest and blobs before it changes a new private sandbox. It never writes into a live resumed sandbox. Providers localProcessSandbox() — runs on the host (no isolation; dev loop only). dockerSandbox({ image }) — isolated container; snapshots, fork, resume-by-id. daytonaSandbox({ apiKey, snapshot, autoStopInterval, ephemeral }) — Daytona cloud sandbox; snapshots after setup; resume starts stopped or archived sandboxes. /workspace maps to /home/daytona/workspace . Setup that installs packages must use sudo -n (do not deny sudo * ). See docs/sandbox/providers.md for network and secret injection details. All implement the same SandboxHandle : fs (read/write/list/mkdir/remove/ rename/exists), git (clone/status/add/commit/push/pull/branch), process ( exec + duplex spawn ), ports.connect(port) , env.set , optional snapshot() / fork() , destroy() . Providers advertise support via capabilities() ; calling an unsupported optional method throws UnsupportedCapabilityError . Policy import { defineSandboxPolicy } from '@tanstack/ai-sandbox' // Headless Grok Build / Codex: stay on auto-approve. Isolation is the // outer sandbox (Docker, Daytona, …), not commands.deny on this policy. const policy = defineSandboxPolicy ({ default : 'allow' , }) // pass to defineSandbox({ policy }); harness adapters map it to native permissions Claude Code can use default: 'ask' plus allow/ask/deny lists. Use Claude Code when you need command-level deny. Provider privilege rules (non-root users, network block at create) live in docs/sandbox/providers.md . Lifecycle & resume reuse: 'thread' resumes one sandbox per threadId ; the compound key folds in provider + workspace hash + tenant so changing the repo/setup/image starts fresh. Ensure order: resume running → restore snapshot → create + bootstrap. Instance durability (durable resume) Resume bookkeeping defaults to in-memory (single-process). For cross-process / multi-replica resume, implement a durable SandboxInstanceStore (BYO) and pass it as withSandbox(sandbox, { instances }) . Pair multi-replica with a distributed lock: either withLocks from @tanstack/ai/locks (ordered before withSandbox ) or the locks option. import { chat, toServerSentEventsResponse } from '@tanstack/ai' import { InMemoryLockStore , withLocks } from '@tanstack/ai/locks' import { claudeCodeText } from '@tanstack/ai-claude-code' import { withSandbox } from '@tanstack/ai-sandbox' // Your `defineSandbox(...)` result. import { sandbox } from './sandbox' // Production: your BYO store — docs/sandbox/durability.md import { instanceStore } from './sandbox-instance-store' export async function POST ( request : Request ) { const { threadId, messages } = await request. json () const stream = chat ({ threadId, adapter : claudeCodeText ( 'sonnet' ), messages, middleware : [ withLocks ( new InMemoryLockStore ()), // multi-replica: distributed lock withSandbox (sandbox, { instances : instanceStore }), ], }) return toServerSentEventsResponse (stream) } The store option takes precedence over an ambient SandboxInstanceStoreCapability (provided by a platform layer via provideSandboxInstanceStore ), which in turn beats the in-memory fallback. Chat transcript durability ( withPersistence ) is independent — compose both when the app needs history and instance reuse. Prove adapters with runSandboxInstanceStoreConformance from @tanstack/ai-sandbox/testkit . Use defineSandboxInstanceStore({ get, upsert, delete }) for inline typing of a BYO store (same pattern as defineLock / defineMessageStore ). File-event hooks Watch the workspace for create/change/delete events. Provider-agnostic: native fs.watch on local-process, a portable find poll on Docker/exec-only providers (no extra deps or image changes). Declare hooks on defineSandbox({ hooks }) (sandbox-scoped) or on any chat middleware via the sandbox group (run-scoped): import { defineSandbox, withSandbox } from '@tanstack/ai-sandbox' // `defineChatMiddleware` is core's, not this package's — `@tanstack/ai-sandbox` // consumes it too (see its own `src/middleware.ts`). import { chat, defineChatMiddleware } from '@tanstack/ai' import { claudeCodeText } from '@tanstack/ai-claude-code'