Skip to main content

Harness Auth

还没翻译译自英文（tanstack.com）本页 19 段都还没译

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

Host login

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

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

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

See Harnesses for which adapter to pick, and Providers for scrubEnv on local-process.

Edit on GitHub
AI 翻译查看英文原文