CLIProxyAPI hub
One home machine holds every Claude, Codex and xAI login. Every other host calls that machine over Tailscale. Source guide: https://gist.github.com/t3dotgg/59a521d2ee8d70aaf90e280c175072af
Tool: cliproxy-hub in itsryanarmani/scripts.
Two hard rules
- Claude seats run in Claude Code only. Codex seats run in Codex only. A tool uses the hub by running Claude Code or Codex on its host. Do not call the hub from any other tool with a Claude or Codex seat.
- The hub is a home machine. Never a VPS or a datacenter host. Never serve other people's traffic with these seats.
The guide says a ban is possible. Tell the user this before you start.
Set up the hub
Install and start:
brew install cliproxyapi && brew services start cliproxyapi.In the config, bind
host: "127.0.0.1", setapi-keys, and set a managementsecret-key.Put the hub on the tailnet. Run this in a real Terminal window, not from an agent shell. The macOS Tailscale app refuses
servefrom an agent shell. HTTPS must be on in the Tailscale admin console.cliproxy-hub serveKeep the hub awake. A sleeping hub stops every client.
sudo pmset -c sleep 0-capplies on power only, and the Mac still sleeps when you close the lid. Turn on automatic login so the service starts again after a reboot. A hub set up with the old command still has the lid-closed setting: runsudo pmset -a disablesleep 0to remove it.Keep the hub up to date. An old build sends an old Grok CLI version, and xAI returns
426 ... CLI version is outdated. Runbrew upgrade cliproxyapiandbrew services restart cliproxyapi. Seats survive the upgrade.
Check health
cliproxy-hub check
/v1/models lists models even when every seat is dead. Trust the seats: lines.
A client call to a dead seat returns 503 auth_unavailable.
Log in or repair a seat
A seat dies when its refresh token expires or is revoked. Log in again on the hub machine, one seat at a time:
tail -f /dev/null | cliproxyapi -claude-login -no-browser # Claude
tail -f /dev/null | cliproxyapi -codex-login -no-browser # Codex
tail -f /dev/null | cliproxyapi -xai-login -no-browser # xAI (Grok)
The tail -f /dev/null | part keeps stdin open. Without it the login exits when stdin
closes and the browser callback finds nothing.
Rules that each cost a failed attempt:
- Use the Chrome profile that matches the seat. A wrong profile adds a seat for the wrong account.
- Close every old
localhost:54545(Claude) orlocalhost:1455(Codex) tab first. A stale tab retries its old callback and the login stops withState mismatch. - Open each link once. A link works only with the login process that printed it.
- Finish within about 5 minutes. The login times out.
- After the login, run
cliproxy-hub checkand confirm the seat showsok. - Move a retired seat file out of
~/.cli-proxy-api. Do not delete it.
Boat boxes: one command
Run this on the home Mac. It needs no prompt, no variables and no pasted keys:
boat-hub new <repo>
It reads the hub URL and key files from ~/Documents/Personal/.secrets
(cliproxy-hub.env, cliproxy-hub-key, the newest tailscale-authkey-boat-hub-*). The box
joins the tailnet, wires Claude Code, Codex and pi, and pulls the latest main of the repo
and of private-repo-b1e6. A repo with a <repo>-ready snapshot starts faster. Any other repo
starts from hub-ready and clones on first boot. Make a snapshot with boat-hub warm <repo>, which needs a Boat environment named for the repo.
Each snapshot costs storage, so keep few. On the box, run claude-hub and codex-hub.
A bare claude has no hub login.
Point a client host at the hub
Every client host needs Tailscale on the same tailnet and a Claude Code or Codex install.
- Put the hub URL and key on the host. Write the key to a 0600 file. Never paste it in chat.
- Run:
export HUB_URL="https://<hub>.<tailnet>.ts.net:8317"
export HUB_KEY_FILE=~/.hub-key
cliproxy-hub verify
cliproxy-hub client claude # writes ~/.claude-hub/settings.json
cliproxy-hub client codex # writes ~/.codex-hub/config.toml
- Start the tools with the second config dir. The normal install stays unchanged:
CLAUDE_CONFIG_DIR=~/.claude-hub claude
CODEX_HOME=~/.codex-hub codex
Pass --config-dir or --codex-home to replace the normal config instead. The script
backs up the old file first.
A client on a datacenter host is fine, because only the hub talks to Anthropic and OpenAI. Never log in to a seat on a client host.
Antigravity subscription
Antigravity uses a separate Google subscription credential on the home hub. It does not use a Gemini API billing key. Existing clients keep their hub URL and key. They need no Google login. Subscription proxy use can risk account restrictions; confirm the owner's intent before adding this access.
Add the subscription on the hub
- Confirm that
cliproxyapi -hlists-antigravity-login. - Reuse the signed-in Antigravity app credential when possible.
- Validate token refresh with the OAuth client that CLIProxyAPI uses for refresh. Validate account identity before writing a hub credential.
- Discover the project through
loadCodeAssistwithmetadata.ideType: ANTIGRAVITY. - Require a successful response and a project ID.
- Set the credential type to
antigravity. - Set a unique credential prefix, such as
antigravity-personal. Setforce-model-prefix: truebefore adding the credential. In the v8 config layout, this option lives underrouting. Older layouts use the top-level option. Check the installed version's layout. Confirm the running value through the management API. A saved file alone does not prove that the setting is active. Withfalse, unprefixed requests can use this credential when model IDs overlap. Withtrue, unprefixed requests use credentials without a prefix. Check other prefixed credentials before changing this global option. Update clients that use their unprefixed IDs to use the corresponding prefixed IDs. - Stage the credential outside Git with mode
0600. - Parse the staged JSON before installing it in the hub auth directory.
- Back up an existing credential before replacement.
On macOS, the app's Keychain item uses service gemini and account
antigravity. The value uses go-keyring-base64: around JSON with a nested
token object. Read it inside one process. Decode it in that process.
Never print the value. This storage format is verified on 2026-11-07 UTC.
Use CLIProxyAPI's OAuth client when validating refresh compatibility.
Preserve the app's Keychain entry.
If reuse fails, follow the owner's seat-login rules. The supported login command
is cliproxyapi -antigravity-login -no-browser; it still needs a browser callback.
Never start a new login merely because model discovery fails.
The hub record needs access_token, refresh_token, expires_in, timestamp
(milliseconds), expired (RFC 3339), email, and project_id, plus its type
and prefix. Keep account names, project IDs, tokens, and private hub URLs out of
issues, PRs, screenshots, and public examples.
Discover and use models
Run cliproxy-hub verify from an existing client.
Read the authenticated /v1/models catalog through the existing shared HTTPS URL.
Select an exact <prefix>/<model> ID from that catalog.
Use the credential prefix configured in step 7.
The prefix selects the Antigravity subscription when model names overlap.
Send one small request to that ID. Require a successful inference response.
Also check the provider's management seat state on the hub.
A model list alone does not prove the credential can serve requests.
Refresh client model lists after adding the credential. A client with a fixed
catalog needs an explicit entry for the discovered prefixed ID.
On 2026-11-07 UTC, the cliproxy-hub client pi catalog contains only Codex and Grok.
At the owner's direction, add Antigravity to providers.hub.models in pi's
models.json. Copy an existing model entry's shape. Set the ID to the discovered
prefixed ID. Set an Antigravity display name. Keep the existing hub endpoint
and key-file reference. Check the owner's client rules before using other tools.
Claude subscription seats remain restricted to Claude Code.
Check subscription usage
Enable Antigravity in CodexBar's Providers settings.
The usage JSON can contain an account email. Keep the raw output private.
Capture codexbar usage --provider antigravity --json in a mode 0600 file on the hub.
Compare its account email with the hub credential's email privately.
Attribute quota to the hub credential only when the identities match.
The signed-in app can supply measured weekly and five-hour quota windows.
Check the reported source and quota fields before treating the result as live.
Share only selected quota fields.
Request token counts describe a call; they do not measure remaining quota.
See the upstream CodexBar Antigravity notes and CLIProxyAPI Antigravity login implementation.
Tools that cannot use the hub
The hub only serves Claude, Codex, xAI, Kimi and Antigravity seats. Cursor, Devin and
Muse keep their own logins on each host: cursor-agent login, devin auth login,
muse login. They print a code or a link for a browser. A tool that calls models
directly never receives a Claude or Codex seat. It runs Claude Code or Codex.
T3 Code
T3 Code uses the CLI config of the machine that runs the provider. For Codex, choose "Use existing CLI". "Continue with ChatGPT" does not use the hub.
Prompt for an agent on a client host
Copy this to the agent on a new host. Fill in the hub URL.
Set this host up as a client of our CLIProxyAPI hub. Rules: Claude seats run only in
Claude Code and Codex seats run only in Codex. Never print, paste or commit the hub key.
Never log in to a Claude or Codex seat on this host. Do not edit the normal ~/.claude
or ~/.codex config.
1. Read the cliproxy-hub skill in itsryanarmani/skills and use cliproxy-hub from
itsryanarmani/scripts.
2. Check Tailscale is on the same tailnet as the hub: tailscale status.
3. Put the hub key in ~/.hub-key and the Tailscale key in ~/.ts-authkey, both mode 600.
Copy them from the home Mac with scp, never through chat. Set HUB_URL and HUB_KEY_FILE.
If Tailscale is off, run: sudo tailscale up --auth-key=file:$HOME/.ts-authkey. Then delete
~/.ts-authkey.
4. Run: cliproxy-hub verify. Expect "hub reachable".
5. Run these three commands: cliproxy-hub client claude, then cliproxy-hub client codex,
then cliproxy-hub client pi.
6. Test once with Claude Code and Codex: CLAUDE_CONFIG_DIR=~/.claude-hub claude -p "say ok" and
CODEX_HOME=~/.codex-hub codex exec "say ok".
7. Report which commands passed. If one failed, quote the error with any key, token or
header removed, and stop.
Verify from a client
cliproxy-hub verify
Expect hub reachable: N models. Then send one small request with each tool.
Traps
These traps apply when you make a Boat box that uses the hub (boat-hub).
boat env listprints secret values. Do not run it raw in an agent session. Print thenamefields only.boat env add-repochanges the environment. A probe that adds a repo leaves it there. Probe in a throwaway environment, then delete that environment.- The connected-repo list can be stale. Boat can reject a newer repo with "not found in your connected GitHub repos". Open the dashboard. Go to Environment, then GitHub repositories, then Add Repository, then Refresh. A new login does not fix this. A change to the GitHub app permissions does not fix this.
- A box made with
--from <snapshot>can skip environment injection. It then has no GitHub login and no repo clone. A box made without--fromhad both. Test that snapshot path with one canary box before you rely on it. boat-hub warmcan hide a clone error and then wait five minutes. The hide was|| truewith the output discarded. Capture the error and print it.- Agent logins inside a box expire. A queued prompt can stay "queued" with no process and no error. Run a one-word canary prompt first. Check that an agent process exists. Then fan out.
- Check the trial limits and the wallet with
boat onboard --jsonbefore you make several boxes. - Delete idle boxes. They bill the wallet.
set -- $vardoes not split in zsh. Pass explicit arguments, or use${=var}.PATHdiffers in a background shell.ghandboatcan be missing there. ExportPATHin that command.- A delegate task runs in that thread's own project. From a scratch folder with no repo, it cannot make a worktree. Make the worktree yourself. Run the worker CLI in that worktree.
- Judge a worker on its diff and on its pull request. Do not judge it on its exit code.