TanStack
Harness

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

shell
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-build

Give each provider a login, and give each adapter authMode: 'host':

ts
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

  1. The user runs /connect:codex.
  2. The harness runs codex login --device-auth on the machine. For Grok Build, it runs grok login --device-auth.
  3. The session sends a harness.auth_required event with the sign-in page (url) and the code (userCode).
  4. The user opens the page, signs in, and types the code.
  5. 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:

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

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

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

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

  1. A saved API key.
  2. The plan sign-in.
  3. The env var, for example CODEX_API_KEY.
  4. 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:

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

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.