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.

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)],
})

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.

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'],
})

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:

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:

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)
}