Persistence (Advanced)
- GenerationsUpdated
- Realtime Voice Chat
- Text-to-Speech
- Transcription
- Transcription: Advanced
- Voice Creation
- Audio Recording
- Audio Generation
- Image Generation
- Image Generation: AdvancedUpdated
- Video Generation
- Video Generation: Advanced
- Live Generation
- World Generation
- Motion GenerationNew
- 3D Model GenerationNew
- 3D Model Generation: AdvancedNew
- Generation HooksUpdated
- Build your first harness
- Host options
- Send and show media
- Connect clients
- Write a client in any language
- Access and tenants
- Run in the terminal
- Deploy a harness
- Send inputs safely
- Run a tool without a model
- Durable sessions
- Run background work on workers
- List, rename, and fork sessions
- Lifecycle and retention
- Run side effects once
- Wait for a person
- Build on the session log
- Control how a turn ends
- Store settings per thread
- Compact a long session
- Fork and reset a thread
- One log for a session tree
- Write a plugin
- Track usage and cost
- Ask before risky tool calls
- Give your agent coding tools
- Sandbox and extend the coding tools
- Run the coding tools for many threads
- Undo a turn
- Build a coding agent
- Delegate to coding agents
- Switch between agent profiles
- Auth and connectors
- Share a thread between people
- Connect model providersUpdated
- Sign in with a ChatGPT or SuperGrok planNew
- Build your own UI
- Code mode in a harness
- Work until a goal is met
- Run agents from a harness
- Hand off a conversation
- Add skills
- Use MCP servers
- Give your agent a computer
- Use from any MCP client
- Use a harness from an editor (ACP)
- Overview
- Quick Start
- Providers
- Harnesses
- Harness AuthUpdated
- Workspace
- Tools
- Policy
- Lifecycle & Snapshots
- Portable Snapshots
- Keep Files After Reload
- Save a Named Version
- Branch From a Version
- Send a Frozen File
- Let the Agent Save and Fork
- Pick Which Files to Keep
- What a Snapshot Stores
- Checkpoint at Any Time
- Store Checkpoints
- Instance Durability
- Durable Runs
- Events
Sandboxes (Advanced)
- Runtime Context
- Bring Your Own Key
- Keep Keys on the Server
- Debug Logging
- Multimodal Content
- Files API
- Per-Model Type Safety
- Runtime Adapter Switching
- Tree-Shaking
- Extend Adapter
- Extend Adapter: Advanced
- Typed Pre-Configured Options
- Test with a Fake Model
- Prompt Caching
- Mid-Conversation Changes
- Approval Flow Processing
Harness Auth
Pass credentials into localProcessSandbox() yourself. The sandbox type does not know whether the machine has grok login or only an API key.
You tell it with authMode on the harness adapter:
- 'api-key' (default): inject the key and use it. Use this in Docker, in a cloud sandbox, on a CI runner, or on any machine with no CLI login.
- 'host': use the CLI login on the machine. Do not inject an API key into that process. Codex and Grok Build can also use this login in Docker and in a cloud sandbox.
You can set authMode in two places:
- On the adapter factory: grokBuildText('composer-2.5', { authMode: 'host' }).
- For one call: chat({ modelOptions: { authMode: 'host' } }).
Use an API key#
This is the default, so you can omit authMode. Pass the key as a workspace secret:
import { chat } from '@tanstack/ai'
import { GROK_CLI_INSTALL_COMMAND, grokBuildText } from '@tanstack/ai-grok-build'
import {
createSecrets,
defineSandbox,
defineWorkspace,
githubRepo,
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: githubRepo({ repo: 'owner/app' }),
setup: [GROK_CLI_INSTALL_COMMAND],
secrets: createSecrets({
XAI_API_KEY: process.env.XAI_API_KEY ?? '',
}),
}),
})
const stream = chat({
threadId: 'thread-1',
adapter: grokBuildText('composer-2.5'),
messages: [{ role: 'user', content: 'Summarize this repo.' }],
middleware: [withSandbox(sandbox)],
})Use the host login#
If the machine already ran grok login, claude login, or codex login, use this setup:
import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import { defineSandbox, defineWorkspace, withSandbox } from '@tanstack/ai-sandbox'
import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
const sandbox = defineSandbox({
id: 'repo-agent',
provider: localProcessSandbox({
scrubEnv: ['XAI_API_KEY', 'GROK_API_KEY'],
}),
workspace: defineWorkspace({
source: { type: 'local', path: '/abs/path/to/repo' },
}),
})
const stream = chat({
threadId: 'thread-1',
adapter: grokBuildText('composer-2.5', { authMode: 'host' }),
messages: [{ role: 'user', content: 'Summarize this repo.' }],
middleware: [withSandbox(sandbox)],
})scrubEnv removes keys from the env of each command, for example a key that a workspace secret sets. If the CLI sees XAI_API_KEY, it can use that key and not your login. The keys of the host process do not reach the command.
With authMode: 'host', the Codex and Grok Build adapters also remove the key variables from the CLI process:
- Codex: CODEX_API_KEY and OPENAI_API_KEY.
- Grok Build: XAI_API_KEY and GROK_API_KEY.
The command gets only a few variables of the host process. If your login or your network needs more, for example CLAUDE_CONFIG_DIR, CODEX_HOME, HTTPS_PROXY, or SSH_AUTH_SOCK, name them in passEnv:
import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
const provider = localProcessSandbox({
passEnv: ['CODEX_HOME', 'HTTPS_PROXY'],
})Use the host login in Docker or a cloud sandbox#
Your machine already has a Codex or Grok Build login, from codex login, grok login, or /connect in a harness. Set authMode: 'host', and the adapter lends that login to the sandbox for each run:
import { chat } from '@tanstack/ai'
import { codexText } from '@tanstack/ai-codex'
import { defineSandbox, defineWorkspace, githubRepo, 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: githubRepo({ repo: 'owner/app' }),
setup: ['npm install -g @openai/codex --include=optional && codex --version'],
}),
})
const stream = chat({
threadId: 'thread-1',
adapter: codexText('gpt-6.1-sol', { authMode: 'host' }),
messages: [{ role: 'user', content: 'Summarize this repo.' }],
middleware: [withSandbox(sandbox)],
})For each run, the adapter does this:
- Before the run, it copies the login file of the machine into the home folder of the sandbox.
- After the run, it reads the file back. If the CLI refreshed the token, it writes the new file to the machine. If you signed in again on the machine during the run, it keeps your new login.
- Then it deletes the file from the sandbox. It does this also when the run fails or you abort it.
So a sandbox that stays alive, or a snapshot of it, does not keep the login. On a local-process sandbox, nothing is copied: the CLI reads the file of the machine.
Runs on the same sandbox share one copy. The last run to end deletes it. The count is kept in one server process, so run all the runs of one sandbox from one server.
A durable run is different, because its agent can run on after the host stops:
- When the host stops reading before the agent ends, the login stays in the sandbox, so the agent can keep working.
- The host that attaches to the run uses that login, and deletes it when the run ends.
- If the agent refreshed the token, the attaching host writes it to the machine. If you signed in again on the machine before the attach, it keeps your new login.
- A new run on that sandbox shares the kept login, and does not delete it.
- If no host attaches, the login stays in the sandbox until you destroy the sandbox.
The login files:
| Adapter | Login file on the machine |
|---|---|
| Codex | $CODEX_HOME/auth.json, or ~/.codex/auth.json. The adapter reads CODEX_HOME of the server process. |
| Grok Build | ~/.grok/auth.json |
If the file is missing, the run fails with No Codex login on this machine. Run /connect:codex. A Codex login in the OS keyring has no file, so it also fails. See Codex logins in the OS keyring.
Run one sandbox at a time for each login. If two runs refresh the token at the same time, the last write wins, and the other copy can stop working.
What each harness reads#
| Adapter | authMode: 'api-key' (default) | authMode: 'host' |
|---|---|---|
| Grok Build | XAI_API_KEY | grok login |
| Claude Code | ANTHROPIC_API_KEY | claude login |
| Codex | CODEX_API_KEY | codex login |
| ACP-Compatible | Set authMethodId (for Grok, xai.api_key). | Skips ACP authenticate. |
OpenCode reads OPENAI_API_KEY from its env. It has no authMode flag. On local-process, the key of the host process does not reach it: set the key as a workspace secret or with env.set.
Let the user pick (client and server)#
The React chat example has this choice on /repo-report. The client sends authMode. The server builds the adapter with that value.
Client:
import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
function Report() {
const { sendMessage } = useChat({
connection: fetchServerSentEvents('/api/sandbox-repo-report'),
threadId: 'support-chat',
forwardedProps: { authMode: 'api-key' },
})
return (
<button type="button" onClick={() => sendMessage('Report on this repo')}>
Run
</button>
)
}Server:
import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import { withSandbox } from '@tanstack/ai-sandbox'
import { sandbox } from './sandbox'
export async function POST(request: Request) {
const body: unknown = await request.json()
const forwarded =
typeof body === 'object' &&
body !== null &&
'forwardedProps' in body &&
typeof body.forwardedProps === 'object' &&
body.forwardedProps !== null
? body.forwardedProps
: {}
const authMode =
'authMode' in forwarded && forwarded.authMode === 'host'
? 'host'
: 'api-key'
const threadId =
typeof body === 'object' &&
body !== null &&
'threadId' in body &&
typeof body.threadId === 'string'
? body.threadId
: undefined
if (!threadId) {
return new Response('Send a threadId.', { status: 400 })
}
const stream = chat({
adapter: grokBuildText('composer-2.5', { authMode }),
messages: [{ role: 'user', content: 'Report on this repo' }],
threadId,
stream: true,
middleware: [withSandbox(sandbox)],
})
return toServerSentEventsResponse(stream)
}The server accepts only 'host' or 'api-key'. Any other value falls back to 'api-key'.
To pick the agent, see Harnesses. For scrubEnv, passEnv, and other local-process options, see Providers (Advanced).