Harnesses

A harness adapter is the second axis of a sandboxed run: it decides which coding agent runs and translates that agent's work back into chat() stream chunks. The provider decides where the agent runs; the harness decides what runs. Both sit behind the same chat() + withSandbox() wiring, so you can swap a harness without touching your provider or workspace.

Every harness adapter declares requires: [SandboxCapability], so chat() fails fast at the call site unless a sandbox is provided via withSandbox(...).

Built-in harness adapters#

Each agent has its own package with curated per-model metadata. Pass the adapter to chat({ adapter }) and run it under any provider.

import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import { withSandbox } from '@tanstack/ai-sandbox'
import { sandbox } from './sandbox'
import { messages } from './chat-context'

const stream = chat({
  adapter: grokBuildText('grok-build'),
  messages,
  middleware: [withSandbox(sandbox)],
})

import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import { withSandbox } from '@tanstack/ai-sandbox'
import { sandbox } from './sandbox'
import { messages } from './chat-context'

const stream = chat({
  adapter: grokBuildText('grok-build'),
  messages,
  middleware: [withSandbox(sandbox)],
})

Any ACP agent (acpCompatible)#

Many coding agents speak the Agent Client Protocol (ACP) — pi, gemini --acp, and dozens of others. For any of them that doesn't have a dedicated package, acpCompatible (from @tanstack/ai-acp) builds a harness adapter on the spot — the harness equivalent of openaiCompatible. Configure how to launch it once, then run it under any provider like the built-in adapters:

import { acpCompatible } from '@tanstack/ai-acp'

const pi = acpCompatible({
  name: 'pi',
  models: ['pi-fast', 'pi-pro'],
  command: ({ model, harnessCwd }) => `pi --acp -m ${model} --cwd ${harnessCwd}`,
  authMethodId: 'pi-api-key',
})

import { acpCompatible } from '@tanstack/ai-acp'

const pi = acpCompatible({
  name: 'pi',
  models: ['pi-fast', 'pi-pro'],
  command: ({ model, harnessCwd }) => `pi --acp -m ${model} --cwd ${harnessCwd}`,
  authMethodId: 'pi-api-key',
})

See the ACP-Compatible Harness guide for the full config (typed models, per-call modelOptions, WebSocket transports, permissions, and protocol coverage). For which agents you can plug in, browse the official ACP agents list and the ACP registry.

Where to go next#

• Providers — where the harness runs (local, Docker, Daytona, Vercel, Sprites).
• Tools — bridge your app's own tools into the in-sandbox agent.
• Events & File Hooks — stream the agent's edits and activity to a UI.