Harness Auth

Your laptop already has grok login, claude login, or codex login. A GitHub runner has no browser login. It only has an API key. Both can use localProcessSandbox().

Set authMode on the adapter. The sandbox type does not pick the credentials. The default is 'api-key'. Most harnesses run in Docker or a cloud sandbox. Those have no host CLI login.

'api-key' (default): inject the key and use it.
'host': use the CLI login on the machine. Do not inject an API key into that process.

Pass authMode in one of two places:

Adapter factory: grokBuildText('composer-2.5', { authMode: 'host' })
One call: chat({ modelOptions: { authMode: 'host' } })

Use this when the machine already ran grok login, claude login, or codex login.

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'
import { messages, threadId } from './chat-context'

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,
  adapter: grokBuildText('composer-2.5', { authMode: 'host' }),
  messages,
  middleware: [withSandbox(sandbox)],
})

scrubEnv removes keys the host process inherited. If the CLI sees XAI_API_KEY, it can prefer that key over your login.

API key

This is the default. Use it on a runner, in Docker, or on any machine that has no CLI login. You can omit authMode.

import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import {
  createSecrets,
  defineSandbox,
  defineWorkspace,
  githubRepo,
  withSandbox,
} from '@tanstack/ai-sandbox'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
import { messages, threadId } from './chat-context'

const sandbox = defineSandbox({
  id: 'repo-agent',
  provider: dockerSandbox({ image: 'node:22' }),
  workspace: defineWorkspace({
    source: githubRepo({ repo: 'owner/app' }),
    secrets: createSecrets({
      XAI_API_KEY: process.env.XAI_API_KEY ?? '',
    }),
  }),
})

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

Each harness

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)	skip ACP authenticate

OpenCode still reads OPENAI_API_KEY from the process env. It has no authMode flag.

Client and server

The React chat example exposes the same 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'),
    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 stream = chat({
    adapter: grokBuildText('composer-2.5', { authMode }),
    messages: [{ role: 'user', content: 'Report on this repo' }],
    stream: true,
    middleware: [withSandbox(sandbox)],
  })

  return toServerSentEventsResponse(stream)
}