Persistence (Advanced)
- GenerationsUpdated
- Realtime Voice Chat
- Text-to-Speech
- Transcription
- Transcription: Advanced
- Voice Creation
- Audio Recording
- Audio Generation
- Image Generation
- Image Generation: AdvancedUpdated
- Video Generation
- Video Generation: Advanced
- Live Generation
- World Generation
- Motion GenerationNew
- 3D Model GenerationNew
- 3D Model Generation: AdvancedNew
- Generation HooksUpdated
- Build your first harness
- Host options
- Send and show media
- Connect clients
- Write a client in any language
- Access and tenants
- Run in the terminal
- Deploy a harness
- Send inputs safely
- Run a tool without a model
- Durable sessions
- Run background work on workers
- List, rename, and fork sessions
- Lifecycle and retention
- Run side effects once
- Wait for a person
- Build on the session log
- Control how a turn ends
- Store settings per thread
- Compact a long session
- Fork and reset a thread
- One log for a session tree
- Write a plugin
- Track usage and cost
- Ask before risky tool calls
- Give your agent coding tools
- Sandbox and extend the coding tools
- Run the coding tools for many threads
- Undo a turn
- Build a coding agent
- Delegate to coding agents
- Switch between agent profiles
- Auth and connectors
- Share a thread between people
- Connect model providersUpdated
- Sign in with a ChatGPT or SuperGrok planNew
- Build your own UI
- Code mode in a harness
- Work until a goal is met
- Run agents from a harness
- Hand off a conversation
- Add skills
- Use MCP servers
- Give your agent a computer
- Use from any MCP client
- Use a harness from an editor (ACP)
- Overview
- Quick Start
- Providers
- Harnesses
- Harness AuthUpdated
- Workspace
- Tools
- Policy
- Lifecycle & Snapshots
- Portable Snapshots
- Keep Files After Reload
- Save a Named Version
- Branch From a Version
- Send a Frozen File
- Let the Agent Save and Fork
- Pick Which Files to Keep
- What a Snapshot Stores
- Checkpoint at Any Time
- Store Checkpoints
- Instance Durability
- Durable Runs
- Events
Sandboxes (Advanced)
- Runtime Context
- Bring Your Own Key
- Keep Keys on the Server
- Debug Logging
- Multimodal Content
- Files API
- Per-Model Type Safety
- Runtime Adapter Switching
- Tree-Shaking
- Extend Adapter
- Extend Adapter: Advanced
- Typed Pre-Configured Options
- Test with a Fake Model
- Prompt Caching
- Mid-Conversation Changes
- Approval Flow Processing
Sign in with a ChatGPT or SuperGrok plan
Add login: codexPlanLogin() to the Codex provider in providerKeys. Then /connect:codex signs the user in with their own ChatGPT plan, and the Codex adapter runs with that login and no API key. Grok Build works the same way with grokBuildPlanLogin() and a SuperGrok plan.
Use this for a harness that runs on the computer of the user: a CLI or a desktop app. The login belongs to the machine, so it is not for a hosted app with many users.
1. Add the plan login on the server#
npm i @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-codex @tanstack/ai-grok-buildpnpm add @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-codex @tanstack/ai-grok-buildyarn add @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-codex @tanstack/ai-grok-buildbun add @tanstack/ai-harness @tanstack/ai-persistence @tanstack/ai-openai @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-codex @tanstack/ai-grok-buildGive each provider a login, and give each adapter authMode: 'host':
import { defineHarness } from '@tanstack/ai-harness'
import { providerKeys } from '@tanstack/ai-harness/plugins'
import { codexPlanLogin, codexText } from '@tanstack/ai-codex'
import { codexByok } from '@tanstack/ai-codex/byok'
import { grokBuildPlanLogin, grokBuildText } from '@tanstack/ai-grok-build'
import { grokBuildByok } from '@tanstack/ai-grok-build/byok'
import { openaiText } from '@tanstack/ai-openai'
import { defineSandbox, defineWorkspace, localSource } from '@tanstack/ai-sandbox'
import { codingAgents } from '@tanstack/ai-sandbox/harness'
import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
const repo = '/path/to/your/repo'
export const lead = defineHarness({
name: 'acme/lead',
adapter: openaiText('gpt-6.1-sol'),
expose: {
commands: ['connect:codex', 'disconnect:codex', 'connect:grok-build', 'disconnect:grok-build', 'keys'],
},
plugins: () => [
providerKeys({
providers: [
{ ...codexByok, login: codexPlanLogin() },
{ ...grokBuildByok, login: grokBuildPlanLogin() },
],
}),
codingAgents({
sandbox: defineSandbox({
id: 'repo',
provider: localProcessSandbox({ dir: repo }),
workspace: defineWorkspace({ source: localSource(repo) }),
}),
agents: {
codex: {
adapter: codexText('gpt-6.1-sol', { authMode: 'host' }),
description: 'Quick fixes and tests',
},
grok: {
adapter: grokBuildText('grok-4.7-build-fast', { authMode: 'host' }),
description: 'Larger changes and refactors',
},
},
}),
],
})- login turns /connect:codex and /connect:grok-build into a plan sign-in. These commands ask for no key.
- authMode: 'host' makes the adapter use the CLI login of the machine. The default is 'api-key'.
- A plan login can use only the models of the plan. For example, a ChatGPT plan rejects gpt-5.3-codex. Run grok models to see the Grok models of a plan. In Codex, run /model.
- expose.commands lets a client UI run the commands. A CLI from runCli does not need it.
- The codex and grok CLIs must be on the PATH of the machine.
- The lead model needs its own key. See Connect model providers.
For more about codingAgents, see Delegate to coding agents.
2. Connect a plan#
- The user runs /connect:codex.
- The harness runs codex login --device-auth on the machine. For Grok Build, it runs grok login --device-auth.
- The session sends a harness.auth_required event with the sign-in page (url) and the code (userCode).
- The user opens the page, signs in, and types the code.
- The CLI exits, and the command returns Signed in to Codex with your ChatGPT plan.
If the user cancels the command, the harness stops the CLI.
3. Show the page and the code on the client#
A CLI from runCli shows them for you:
Sign in to codex. Open https://auth.example.com/device and enter the code ABCD-1234.For your own UI, first serve the harness. Mount the handler on /api/harness:
import { createHarnessHost, membersOnly } from '@tanstack/ai-harness'
import { createHarnessHandler } from '@tanstack/ai-harness/server'
import { memoryPersistence } from '@tanstack/ai-persistence'
// A long random secret. The UI sends the same one.
const token = process.env.HARNESS_TOKEN
const host = createHarnessHost({
persistence: memoryPersistence(),
access: {
// With no token set, nobody gets in.
getUser: ({ request }) =>
token && request.headers.get('authorization') === `Bearer ${token}`
? { id: 'me' }
: null,
rules: membersOnly(),
},
})
export const handler = createHarnessHandler({ host, harness: lead })The plan login belongs to the machine, so let only the user of the machine in. Set HARNESS_TOKEN on the server, and give the UI the same value. See Access and tenants.
Then listen for signIn on the session view, and run the exposed command:
import { createHarnessClient } from '@tanstack/ai-harness/client'
import { createSessionView } from '@tanstack/ai-harness/view'
const view = createSessionView(
createHarnessClient({
url: '/api/harness',
threadId: 'ada-chat',
headers: { authorization: 'Bearer my-token' },
}),
)
view.on('signIn', ({ connector, url, userCode }) => {
if (!url) return
console.log(`Sign in to ${connector}: open ${url}`)
if (userCode) console.log(`Enter this code on that page: ${userCode}`)
})
export const connectCodex = () => view.runCommand({ name: 'connect:codex' })The client gets only the page and the code. The tokens stay in the login file of the CLI on the machine. The harness keeps no copy of them.
Check the sign-in#
/keys shows the plan:
Codex: signed in with your ChatGPT plan
Grok Build: missing. Run /connect grok-build.For each provider, /keys uses the first of these that it finds:
- A saved API key.
- The plan sign-in.
- The env var, for example CODEX_API_KEY.
- Nothing: missing.
In your own UI, the plan sign-in has state: 'plan' in session.snapshot().plugins['tanstack/provider-keys'].providers.
Where the login lives#
The CLI keeps the login in its own file:
- Codex: $CODEX_HOME/auth.json, or ~/.codex/auth.json when CODEX_HOME is not set.
- Grok Build: ~/.grok/auth.json.
The machine has one login for each CLI, and the terminal of the user shares it. So:
- If the user already ran codex login in a terminal, /keys already shows the plan.
- /disconnect:codex runs codex logout. This also signs the user out of Codex in their terminal. It also deletes a saved Codex key.
Codex logins in the OS keyring#
Codex can keep its login in the OS keyring, with cli_auth_credentials_store = "keyring" or "auto" in ~/.codex/config.toml. Then there is no auth.json, and the harness cannot see the login:
- /keys does not show the plan, also after a good /connect:codex.
- A local-process run still works, because codex reads the keyring itself.
- A Docker or cloud sandbox run fails with No Codex login on this machine. Run /connect:codex.
To fix it, keep the login in a file. Set this in ~/.codex/config.toml, then run /connect:codex again:
cli_auth_credentials_store = "file"Run in Docker or a cloud sandbox#
The sample above uses a local-process sandbox, so the CLI reads the login file of the machine. Docker and cloud sandboxes also work: the adapter copies the login file into the sandbox for each run, and deletes it after the run. See Use the host login in Docker or a cloud sandbox.
Vendor terms#
Each vendor has its own terms for a plan login. Read them before you ship:
- OpenAI: Sign in to Codex and the Terms of Use.
- xAI: the Terms of Service.
Claude plans have no sign-in here. Anthropic does not let third-party apps offer Claude.ai login. See Legal and compliance. Claude Code users sign in with an Anthropic API key.
What you have now#
- /connect:codex and /connect:grok-build sign users in with their own ChatGPT or SuperGrok plan, with no API key.
- Your UI shows the sign-in page and the code. The tokens never go to the browser.
- /keys shows signed in with your ChatGPT plan, and /disconnect signs out.