Providers

A provider is where the sandbox runs: a local process for a fast loop, or an isolated VM in production.

A provider is that place. Every provider has the same contract, so your workspace, policy, and harness stay the same when you change the provider.

Set up a provider#

1. Pick a row from the table.

2. Install its package. This example installs the Docker provider. Use the package from your row.

npm i @tanstack/ai-sandbox-docker

pnpm add @tanstack/ai-sandbox-docker

yarn add @tanstack/ai-sandbox-docker

bun add @tanstack/ai-sandbox-docker

3. Set the env vars from the "Needs" column.

4. Pass the provider to defineSandbox:

import {
  createSecrets,
  defineSandbox,
  defineWorkspace,
  githubRepo,
} from '@tanstack/ai-sandbox'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'

export const repoSandbox = defineSandbox({
  id: 'repo-agent',
  provider: dockerSandbox({ image: 'node:22' }),
  workspace: defineWorkspace({
    source: githubRepo({ repo: 'owner/app' }),
    setup: ['corepack enable', 'pnpm install'],
    secrets: createSecrets({
      XAI_API_KEY: process.env.XAI_API_KEY ?? '',
    }),
  }),
})

To change the provider, change only the provider line. Here is the constructor for each one:

import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
import { dockerSandbox, sbxSandbox } from '@tanstack/ai-sandbox-docker'
import { daytonaSandbox } from '@tanstack/ai-sandbox-daytona'
import { vercelSandbox } from '@tanstack/ai-sandbox-vercel'
import { spritesSandbox } from '@tanstack/ai-sandbox-sprites'
import { upstashBoxSandbox } from '@tanstack/ai-sandbox-upstash-box'
import { blaxelSandbox } from '@tanstack/ai-sandbox-blaxel'
import { e2bSandbox } from '@tanstack/ai-sandbox-e2b'
import { boxdSandbox } from '@tanstack/ai-sandbox-boxd'
import { railwaySandbox } from '@tanstack/ai-sandbox-railway'

const dev = localProcessSandbox() // runs on your host
const isolated = dockerSandbox({ image: 'node:22' }) // container
const microvm = sbxSandbox() // Docker Sandboxes microVM
const daytona = daytonaSandbox({ apiKey: process.env.DAYTONA_API_KEY })
const vercel = vercelSandbox({ runtime: 'node24' })
const sprites = spritesSandbox({ apiKey: process.env.SPRITES_API_KEY })
const box = upstashBoxSandbox({ apiKey: process.env.UPSTASH_BOX_API_KEY })
const blaxel = blaxelSandbox() // uses the API key or the CLI login
const e2b = e2bSandbox() // reads E2B_API_KEY
const boxd = boxdSandbox({ org: 'acme' }) // reads BOXD_API_KEY
const railway = railwaySandbox() // reads RAILWAY_TOKEN and RAILWAY_ENVIRONMENT_ID

dockerSandbox() and sbxSandbox() come from the same package. Every other provider has its own package. For the edge, see Cloudflare.

How it works#

• The provider decides where the agent runs. The harness decides which agent runs.
• The provider does not pick how the agent signs in. Set authMode on the harness. See Harness Auth.
• Isolated and cloud providers have no host CLI login. Pass API keys as workspace secrets there.
• Provider-native snapshots and resume keep or recreate the provider state. They make bootstrap faster. Portable Snapshots store finished files in your own persistence.

Capabilities#

Each provider reports what it can do with capabilities(). Code that needs an optional capability checks the flag first:

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

const provider = localProcessSandbox()

if (provider.capabilities().snapshots) {
  // This provider can take a snapshot.
} else {
  // Skip the snapshot. Local process has no snapshots.
}

The framework checks these flags for you. For example, bootstrap takes a snapshot only when snapshots is true, so localProcessSandbox skips that step. If you call an unsupported optional method directly, it throws an UnsupportedCapabilityError.

Branch on the flag, not on the provider name. Then your code keeps working when you change the provider.

killableProcesses across the bundled providers#

The run journal reads this flag to decide how to read a run's output. It also limits what a cancel can do. On a false provider, cancel destroys the sandbox. See what cancel means on a provider that cannot kill.

A bring-your-own provider must set this flag too. For the reason behind each value, see Providers (Advanced).

Stop a file call#

Each handle.fs method takes an optional last argument, { signal }. When the signal aborts, the call rejects with an AbortError:

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

const handle = await localProcessSandbox().create({})
const controller = new AbortController()

const text = await handle.fs.read('/workspace/README.md', {
  signal: controller.signal,
})

• E2B gives the signal to each file call. Then an abort also stops a call that already started.
• Local process gives the signal to read, readBytes, and write. Its other methods check the signal before the call starts.
• The other bundled providers check the signal before the call starts.

bootstrapWorkspace(handle, workspace, { signal }) gives its signal to each file call that it makes. A bring-your-own provider must reject a call when the signal is already aborted.

Advanced#

Each provider has its own options and limits: idle timers, ports, network rules, non-root users, and snapshot behavior. Read them in Providers (Advanced) before you go to production.