TanStack
Sandboxes

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:

ts
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:

ts
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:

ts
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:

ts
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:

  1. Before the run, it copies the login file of the machine into the home folder of the sandbox.
  2. 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.
  3. 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:

AdapterLogin 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

AdapterauthMode: 'api-key' (default)authMode: 'host'
Grok BuildXAI_API_KEYgrok login
Claude CodeANTHROPIC_API_KEYclaude login
CodexCODEX_API_KEYcodex login
ACP-CompatibleSet 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:

tsx
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:

ts
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).