feat(ai-harness): sign in with a ChatGPT or SuperGrok plan for Codex and Grok Build #2197
main fromt3/custom-openai-grok-sub·opened View on GitHubUsers 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
loginhook./connect:<id>then runs the CLI login, and sends the URL and the code throughauthRequired. /keyshas a newplanstate. The order is: saved key, plan, env, missing./disconnect:<id>runs the CLI logout. This also signs the user out in their terminal.
- A provider can now have a
@tanstack/ai-sandbox/host-login(new subpath):cliPlanLoginruns a vendor CLI login and reads the URL and the code from its output.mountHostLogincopies 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
.cmdshims such ascodex.cmdstart throughcmd.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 removesCODEX_API_KEYandOPENAI_API_KEYfrom thecodexprocess, and mounts the login into the sandbox.
- New
@tanstack/ai-grok-build:- New
grokBuildPlanLogin(). authMode: 'host'removesXAI_API_KEYandGROK_API_KEY, and mounts the login on both protocols (acpandstreaming-json).
- New
- 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, anddocs/adapters/grok-build.md.
- New page
- E2E:
/connect:codexagainst a fake CLI.testing/e2enow 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.tsinpackages/ai-sandbox: 31 tests.tsc --noEmitfor the package is clean.vitest run tests/provider-keys.test.tsinpackages/ai-harness: 25 tests.tsc --noEmitis clean.vitest run tests/login.test.ts tests/text-adapter.test.tsinpackages/ai-codex(21 tests) andpackages/ai-grok-build(21 tests).tsc --noEmitis clean in both.oxlint --type-awareandoxfmton 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
providerKeyssnapshot shows the plan state after/connectand/disconnect. - An explicit Grok
authMethodId: 'xai.api_key'wins overauthMode: '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):
/connect:codexran the realcodex login --device-auth. The URL and the code came throughauthRequired. After the sign-in, it returnedSigned in to Codex with your ChatGPT plan./connect:grok-builddid the same withgrok login --device-auth./keysshowed both plans.- With bad API keys in the env and
authMode: 'host', a real turn answeredpongon Codex, on Grokacp, and on Grokstreaming-json. - Control: Codex with
authMode: 'api-key'and the same bad keys failed with401 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:
- Install the
codexCLI. - Follow
docs/harness/plan-sign-in.mdto addproviderKeyswithlogin: codexPlanLogin(). - Run
/connect:codex, open the URL, and enter the code. - Run
/keys. It showsCodex: signed in with your ChatGPT plan.
Tests on this branch:
- Unit tests with a fake CLI script and a fake sandbox.
- Windows
.cmdshim 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:
ProviderLogintype from@tanstack/ai-harness/plugins.cliPlanLoginandmountHostLoginfrom@tanstack/ai-sandbox/host-login.
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
Sign in to join this conversation.