하네스 인증

노트북에서는 이미 grok login, claude login 또는 codex login을 실행했습니다. GitHub 러너에는 브라우저 로그인이 없고 API 키만 있습니다. 두 환경 모두 localProcessSandbox()를 사용할 수 있습니다.

어댑터에서 authMode를 설정합니다. 샌드박스 유형이 자격 증명을 선택하지는 않습니다. 기본값은 'api-key'입니다. 대부분의 하네스는 Docker 또는 클라우드 샌드박스에서 실행됩니다. 이 환경에는 호스트 CLI 로그인이 없습니다.

'api-key' (기본값): 키를 주입해 사용합니다.
'host': 머신의 CLI 로그인을 사용합니다. 해당 프로세스에 API 키를 주입하지 않습니다.

다음 두 위치 중 하나에 authMode를 전달합니다.

어댑터 팩토리: grokBuildText('composer-2.5', { authMode: 'host' })
단일 호출: chat({ modelOptions: { authMode: 'host' } })

머신에서 이미 grok login, claude login 또는 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는 호스트 프로세스가 상속한 키를 제거합니다. CLI가 XAI_API_KEY를 확인하면 로그인보다 해당 키를 우선 사용할 수 있습니다.

API 키

이 방식이 기본값입니다. 러너, Docker 또는 CLI 로그인이 없는 머신에서 사용합니다. 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)],
})

각 하네스

어댑터	`authMode: 'api-key'` (기본값)	`authMode: 'host'`
Grok Build	`XAI_API_KEY`	`grok login`
Claude Code	`ANTHROPIC_API_KEY`	`claude login`
Codex	`CODEX_API_KEY`	`codex login`
ACP-Compatible	`authMethodId` 설정 (Grok의 경우 `xai.api_key`)	ACP `authenticate` 건너뛰기

OpenCode는 여전히 프로세스 env에서 OPENAI_API_KEY를 읽습니다. authMode 플래그는 없습니다.

클라이언트 및 서버

React 채팅 예제는 /repo-report에서 동일한 선택 항목을 제공합니다. 클라이언트는 authMode를 전송하고, 서버는 해당 값으로 어댑터를 생성합니다.

클라이언트:

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

서버:

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

하네스에서 선택할 어댑터를 확인하고, 프로바이더에서 local-process의 scrubEnv를 확인합니다.

호스트 로그인​

API 키​

각 하네스​

클라이언트 및 서버​

호스트 로그인

API 키

각 하네스

클라이언트 및 서버