Skip to content
Source
Sign inSign up
TanStack/ai

feat(ai-harness): sign in with a ChatGPT or SuperGrok plan for Codex and Grok Build #2197

OpenAlemTuzlakwants to merge 12 commits intomain fromt3/custom-openai-grok-subopened View on GitHub

AlemTuzlakcommented

Users of a local harness (a CLI or a desktop app) can now run Codex and Grok Build with their own ChatGPT or SuperGrok plan, with no API key. /connect:codex and /connect:grok-build run the device-code login of the vendor CLI. The UI shows the sign-in URL and the code. The adapters then use that login, also in Docker and cloud sandboxes.

Claude is not part of this. Anthropic's terms do not allow third-party apps to offer Claude.ai login.

🎯 Changes

  • providerKeys (@tanstack/ai-harness):
    • A provider can now have a login hook. /connect:<id> then runs the CLI login, and sends the URL and the code through authRequired.
    • /keys has a new plan state. The order is: saved key, plan, env, missing.
    • /disconnect:<id> runs the CLI logout. This also signs the user out in their terminal.
  • @tanstack/ai-sandbox/host-login (new subpath):
    • cliPlanLogin runs a vendor CLI login and reads the URL and the code from its output.
    • mountHostLogin copies the login file into a Docker or cloud sandbox before a run, and copies it back if the CLI refreshed the token. It always deletes the file from the sandbox after the run, also when the run fails or is aborted. On local-process it copies nothing.
    • On Windows, npm .cmd shims such as codex.cmd start through cmd.exe. A cancel kills the whole process tree.
  • @tanstack/ai-codex:
    • New codexPlanLogin().
    • authMode: 'host' now works. Before, the adapter did not read this option. It removes CODEX_API_KEY and OPENAI_API_KEY from the codex process, and mounts the login into the sandbox.
  • @tanstack/ai-grok-build:
    • New grokBuildPlanLogin().
    • authMode: 'host' removes XAI_API_KEY and GROK_API_KEY, and mounts the login on both protocols (acp and streaming-json).
  • Docs:
    • New page docs/harness/plan-sign-in.md, with a section on Codex logins in the OS keyring.
    • Updates to docs/sandbox/auth.md, docs/harness/provider-keys.md, docs/adapters/codex.md, and docs/adapters/grok-build.md.
  • E2E: /connect:codex against a fake CLI. testing/e2e now depends on @tanstack/ai-codex (workspace).

The default authMode is still 'api-key', so nothing changes for current users.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request. (Not run. Only light checks ran locally. See Testing.)
  • I fully understand the code in this pull request, including any code generated with AI assistance.
  • Docs: I updated docs/ for this change, or this change is not user-facing.
  • Changeset: I added a changeset (pnpm changeset), or this PR does not change a published package.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Testing

Commands run (all passed):

  • vitest run tests/host-login.test.ts in packages/ai-sandbox: 31 tests. tsc --noEmit for the package is clean.
  • vitest run tests/provider-keys.test.ts in packages/ai-harness: 25 tests. tsc --noEmit is clean.
  • vitest run tests/login.test.ts tests/text-adapter.test.ts in packages/ai-codex (21 tests) and packages/ai-grok-build (21 tests). tsc --noEmit is clean in both.
  • oxlint --type-aware and oxfmt on the changed files. pnpm test:docs: no broken links.

Review fixes (4cb3386db): each new test fails on the code before the fix.

  • A CLI output chunk that cuts the URL or the code no longer reports half of it.
  • Runs on one sandbox share one login copy. The last run to end removes it.
  • A failed copy removes the file. A release keeps a host login that changed during the run.
  • The providerKeys snapshot shows the plan state after /connect and /disconnect.
  • An explicit Grok authMethodId: 'xai.api_key' wins over authMode: 'host'.

Durable runs (e5ead65fa): a durable agent can run on after its host stops. The login then stays in the sandbox, and the host that attaches uses it and removes it at the end. Tests: tests/attach.test.ts in packages/ai-codex and packages/ai-grok-build (10 and 9 tests). Each test fails when the adapter always removes the login.

Left to CI: the Playwright E2E test, the full testing/e2e typecheck (it needs about 40 package builds), the typecheck of the docs samples, pnpm test:pr, and coverage. The unit tests ran before the merge with main. main changed no file in these packages.

Live proof (Windows, real accounts, local-process sandbox):

  1. /connect:codex ran the real codex login --device-auth. The URL and the code came through authRequired. After the sign-in, it returned Signed in to Codex with your ChatGPT plan.
  2. /connect:grok-build did the same with grok login --device-auth.
  3. /keys showed both plans.
  4. With bad API keys in the env and authMode: 'host', a real turn answered pong on Codex, on Grok acp, and on Grok streaming-json.
  5. Control: Codex with authMode: 'api-key' and the same bad keys failed with 401 Incorrect API key. So 'host' really removes the keys.

Docker and cloud sandboxes did not run live. Unit tests with a fake sandbox cover the copy in, copy back, and delete.

How to test it yourself:

  1. Install the codex CLI.
  2. Follow docs/harness/plan-sign-in.md to add providerKeys with login: codexPlanLogin().
  3. Run /connect:codex, open the URL, and enter the code.
  4. Run /keys. It shows Codex: signed in with your ChatGPT plan.

Tests on this branch:

  • Unit tests with a fake CLI script and a fake sandbox.
  • Windows .cmd shim tests.
  • The E2E test providerKeys(): /connect:codex signs in with the plan through the CLI.

Risk / rollback

The risk is low. All new behavior is behind login and authMode: 'host', and both are opt-in.

Known limits, all in the docs:

  • CLI output: the parse can break if a vendor CLI changes its login output. Then the error shows the raw output.
  • Two runs on one login: if two sandboxes refresh the token at the same time, the last write wins.
  • Codex keyring logins: they have no auth.json, so the harness cannot see them.
  • Durable runs: a kept login stays in the sandbox until a host attaches to that run, or the sandbox is destroyed. New runs on that sandbox share it.
  • One server per sandbox: runs on one sandbox share one login copy only inside one server process.

To roll back, revert this PR.

Public API change

Before

providerKeys({ providers: [codexByok] })
codexText('gpt-6.1-sol', { authMode: 'host' }) // authMode was ignored

After

import { codexPlanLogin } from '@tanstack/ai-codex'
import { grokBuildPlanLogin } from '@tanstack/ai-grok-build'

providerKeys({
  providers: [
    { ...codexByok, login: codexPlanLogin() },
    { ...grokBuildByok, login: grokBuildPlanLogin() },
  ],
})
codexText('gpt-6.1-sol', { authMode: 'host' }) // uses the CLI login

New exports:

  • ProviderLogin type from @tanstack/ai-harness/plugins.
  • cliPlanLogin and mountHostLogin from @tanstack/ai-sandbox/host-login.

Sign in to join this conversation.