Providers

A provider owns the isolation primitive: where the harness actually runs. Every provider implements the same SandboxProvider / SandboxHandle contract, so the workspace you hand the agent and the policy that guards it are provider-agnostic. Pick a provider for the isolation, auth, and snapshot/resume behaviour you need; the rest of your sandbox definition stays the same.

The provider is where the agent runs. For which agent runs (Grok Build, Claude Code, Codex, OpenCode, or any ACP agent via acpCompatible) see Harnesses.

Choosing a provider#

Each provider is its own package, and the constructor is the only thing that differs between them:

import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
import { daytonaSandbox } from '@tanstack/ai-sandbox-daytona'
import { vercelSandbox } from '@tanstack/ai-sandbox-vercel'

const dev = localProcessSandbox() // runs on your host
const isolated = dockerSandbox({ image: 'node:22' }) // runs in a container
const daytona = daytonaSandbox({ apiKey: process.env.DAYTONA_API_KEY }) // managed cloud sandbox
const vercel = vercelSandbox({ runtime: 'node24' }) // managed Vercel microVM

Cloud providers (Daytona, Vercel) run as remote VMs. When you drive them from your laptop, tools bridged from chat() can't dial your machine's localhost, you need the bridge tunnel. See the tools guide for the ngrok subpath, and the Cloudflare guide for the edge-native co-located model.

Local process#

import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'

const dev = localProcessSandbox()

• Isolation: none. The harness runs directly on your host, inheriting your host environment. Use it for trusted or dev work only. There is no boundary between the agent and your machine.
• Auth / env: inherits the host environment. No API key injection is required if your host CLI is already logged in.
• Snapshot / resume: no snapshots and no durable resume-by-id; each run re-creates and re-bootstraps under the same identity. The snapshot step is skipped silently (see Capabilities).

Use a host CLI's own auth (scrubEnv)#

Because localProcessSandbox runs the harness on your host, it inherits your host environment, including any API keys exported there. Use scrubEnv to remove variables before spawning, so the host CLI falls back to its own logged-in session instead of billing the API. For example, drop XAI_API_KEY so Grok Build uses your grok.com login (the same trick works for Claude Code with ANTHROPIC_API_KEY → claude login):

import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'

const hostLogin = localProcessSandbox({ scrubEnv: ['XAI_API_KEY'] })

Only local-process can do this. It is the only provider that runs your host CLI. Isolated and cloud providers have no host login, so they always use an injected API key (supplied as a workspace secret).

Windows process teardown (logger)#

Killing a spawned process means killing the whole tree, and on Windows that takes more than taskkill /T. Commands run through a git-bash sh, and MSYS's fork emulation runs the final command of a statement list, such as the tail -f behind a journal follow read, under an intermediate shell that immediately exits. Windows never reparents, so the surviving process points at a dead parent and taskkill /T, which walks only live parent links, cannot reach it while still exiting 0. Left alone, every follow read leaks a process for the life of the machine.

localProcessSandbox therefore consults MSYS's own process table, which does keep the logical parentage before killing, then kills any descendant /T missed. Teardown is total by construction: it never throws, because a throwing kill would strand a run mid-flight. That means a kill it genuinely cannot complete (a protected process, access denied) is otherwise invisible, so pass a logger to see it:

import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'

const dev = localProcessSandbox({
  logger: {
    warn: (message, meta) => console.warn(message, meta),
  },
})

Any object with a warn(message, meta?) method works, so the InternalLogger your adapter already receives can be handed straight in. A process that had already exited on its own is not a failure and is never reported.

Nothing here changes on POSIX, where sh really is the command's parent and signalling the wrapper is enough.

Docker#

import { dockerSandbox } from '@tanstack/ai-sandbox-docker'

const isolated = dockerSandbox({ image: 'node:22' })

• Isolation: a real container boundary between the agent and your host.
• Auth / env: no host login; provide credentials as workspace secrets, which are injected into the container env at create/resume. The agent reaches host tools over host.docker.internal (see tools).
• Snapshot / resume: full commit-based snapshots, fork, and resume-by-id. Bootstrap snapshots after setup completes, so subsequent runs resume from the snapshot instead of re-running setup.

Daytona#

import { daytonaSandbox } from '@tanstack/ai-sandbox-daytona'

const daytona = daytonaSandbox({ apiKey: process.env.DAYTONA_API_KEY })

• Isolation: a managed cloud sandbox on a remote VM you do not run yourself.
• Auth / env: needs DAYTONA_API_KEY. Harness credentials are injected as workspace secrets; there is no host login to fall back on.
• Snapshot / resume: no snapshots; resume-by-id reconnects to a still-running sandbox (not a restored point-in-time snapshot), plus port preview links for live previews.
• Bridge: the sandbox is remote, so a bridged tool call can't reach your laptop's localhost. In local dev, tunnel the bridge (see tools); a deployed orchestrator is reachable out of the box.

Vercel#

import { vercelSandbox } from '@tanstack/ai-sandbox-vercel'

const vercel = vercelSandbox({ runtime: 'node24' })

• Isolation: a managed microVM (Vercel Sandbox).
• Auth / env: needs VERCEL_TOKEN plus a team/project. Harness credentials are injected as workspace secrets.
• Snapshot / resume: persistent resume-by-id with a durable filesystem, plus exposed-port domains for previews.
• Bridge: like Daytona, it is a remote VM, so bridged tools need the tunnel in local dev (see tools).

Sprites#

import { spritesSandbox } from '@tanstack/ai-sandbox-sprites'

const sprites = spritesSandbox({ apiKey: process.env.SPRITES_API_KEY })

• Isolation: a managed Sprites stateful sandbox (Fly.io), a remote VM you do not run yourself.
• Auth / env: needs SPRITES_API_KEY (token form org/projectNumber/tokenId/secret); override the control-plane URL with apiUrl / SPRITES_API_URL. Harness credentials are injected as workspace secrets.
• Snapshot / resume: resume-by-id reconnects to the named Sprite (its filesystem is durable across idle suspend/resume). snapshot() creates a Sprite checkpoint (a save point of the writable overlay); restore is in-place on the same Sprite via the handle's restoreCheckpoint() / listCheckpoints(). A checkpoint does not survive Sprite deletion, so the provider intentionally does not implement the reconstruct-after-gone restoreSnapshot, when a Sprite is gone the framework degrades to a fresh create instead. Restore restarts the environment and can take minutes; restoreCheckpoint() polls the workspace until it is listable again before resolving. Note that immediately after a restore the overlay can be listable while individual file reads briefly return an I/O error as it settles, so retry reads if you act on the filesystem the instant restore returns.
• Ports: a Sprite proxies a single internal HTTP port (default 8080, configurable via httpPort) to its always-on public URL. ports.connect(8080) switches the URL to public auth and returns it; other ports are not exposed.
• Bridge: like Daytona and Vercel, it is a remote VM, so bridged tools need the tunnel in local dev (see tools).

Capabilities#

Providers declare what they support via capabilities(). The flags are:

Code that uses an optional capability checks the flag first and degrades gracefully. For example, bootstrap only snapshots when snapshots is supported, so localProcessSandbox simply skips the step. Calling an unsupported optional method directly (instead of checking the flag) throws an UnsupportedCapabilityError:

import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'

const provider = localProcessSandbox()
const caps = provider.capabilities()

if (caps.snapshots) {
  // safe to take a snapshot
} else {
  // degrade gracefully, local-process has no snapshots
}

Use the flags to write provider-agnostic code: branch on the capability rather than the concrete provider, and your sandbox definition keeps working when you swap one provider for another.

killableProcesses across the bundled providers#

This flag is measured, not asserted. A wrong true hands the journal reader an unstoppable tail -f and leaks a process per run, so a provider only declares it once killing has been observed to work against a real sandbox. Two of these declarations were once true on reasoning alone and both turned out to be false when probed (Docker's stream destroy left the container-side process in ps; local-process's sh -c did not exec, so killing the shell left the command alive). Anything that cannot be measured yet stays false, because poll is merely slower while a wrong follow is a leak.

Each of the remote providers registers the shared journal conformance suite, so the claim is falsifiable rather than asserted: with credentials present the suite runs against a real sandbox, and without them it reports a named skip carrying the reason instead of a silent pass. Cloudflare's gate is the runtime rather than credentials, its provider can only create a sandbox through a Sandbox Durable Object binding, which no Node test process has, so its registration is a named skip saying exactly that, until a Workers-runtime harness can measure it.

This flag is required on every provider, including a bring-your-own one. A provider that omitted it would be treated as killable, which is the dangerous default: a follower process started there could never be reclaimed, and it would keep running inside the sandbox for as long as the sandbox lives.

It is the flag the run journal reads to decide how to tail a run's output: a killable provider gets a streaming tail -f, and a provider like Cloudflare gets a loop of bounded reads, each of which terminates on its own.

The flag also bounds what cancel can mean. On a false provider there is no signal path to the agent process, so the only cancel that actually stops the agent means destroying the sandbox, which is what the cancel path does. See what cancel means on a provider that cannot kill.