# Cliproxy Hub

> Run one always-on CLIProxyAPI hub on a home machine and point Claude Code and Codex on every other host at it over Tailscale. Load when a host needs Claude, Codex or Grok access without its own login, when the hub shows "token expired", "unauthorized" or a 426 version error, when a client gets 503 auth_unavailable, when adding a seat, or when a Boat box that uses the hub hides a secret, a clone error, or a dead login. Based on Theo's CLIProxyAPI guide.

- Skill: `pooriaarab/cliproxy-hub` (Agent Skill)
- Install (CLI): `npx get-skill add pooriaarab/cliproxy-hub`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pooriaarab/cliproxy-hub/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: pooriaarab (https://skillmd.com/u/pooriaarab)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/pooriaarab/cliproxy-hub

---


# 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

1. 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.
2. 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

1. Install and start: `brew install cliproxyapi && brew services start cliproxyapi`.
2. In the config, bind `host: "127.0.0.1"`, set `api-keys`, and set a management `secret-key`.
3. Put the hub on the tailnet. Run this in a real Terminal window, not from an agent
   shell. The macOS Tailscale app refuses `serve` from an agent shell. HTTPS must be
   on in the Tailscale admin console.

   ```sh
   cliproxy-hub serve
   ```

4. Keep the hub awake. A sleeping hub stops every client.

   ```sh
   sudo pmset -c sleep 0
   ```

   `-c` applies 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: run `sudo pmset -a disablesleep 0` to remove it.
5. Keep the hub up to date. An old build sends an old Grok CLI version, and xAI returns
   `426 ... CLI version is outdated`. Run `brew upgrade cliproxyapi` and
   `brew services restart cliproxyapi`. Seats survive the upgrade.

## Check health

```sh
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:

```sh
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) or `localhost:1455` (Codex) tab first. A stale tab
  retries its old callback and the login stops with `State 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 check` and confirm the seat shows `ok`.
- 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:

```sh
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.

1. Put the hub URL and key on the host. Write the key to a 0600 file. Never paste it in chat.
2. Run:

```sh
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
```

3. Start the tools with the second config dir. The normal install stays unchanged:

```sh
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

1. Confirm that `cliproxyapi -h` lists `-antigravity-login`.
2. Reuse the signed-in Antigravity app credential when possible.
3. Validate token refresh with the OAuth client that CLIProxyAPI uses for refresh.
   Validate account identity before writing a hub credential.
4. Discover the project through `loadCodeAssist` with `metadata.ideType: ANTIGRAVITY`.
5. Require a successful response and a project ID.
6. Set the credential type to `antigravity`.
7. Set a unique credential prefix, such as `antigravity-personal`.
   Set `force-model-prefix: true` before adding the credential.
   In the v8 config layout, this option lives under `routing`.
   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.
   With `false`, unprefixed requests can use this credential when model IDs overlap.
   With `true`, 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.
8. Stage the credential outside Git with mode `0600`.
9. Parse the staged JSON before installing it in the hub auth directory.
10. 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](https://github.com/steipete/CodexBar/blob/main/docs/antigravity.md)
and [CLIProxyAPI Antigravity login implementation](https://github.com/router-for-me/CLIProxyAPI/blob/main/sdk/auth/antigravity.go).

## 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.

```text
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

```sh
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 list` prints secret values. Do not run it raw in an agent session. Print the `name` fields only.
- `boat env add-repo` changes 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 `--from` had both. Test that snapshot path with one canary box before you rely on it.
- `boat-hub warm` can hide a clone error and then wait five minutes. The hide was `|| true` with 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 --json` before you make several boxes.
- Delete idle boxes. They bill the wallet.
- `set -- $var` does not split in zsh. Pass explicit arguments, or use `${=var}`.
- `PATH` differs in a background shell. `gh` and `boat` can be missing there. Export `PATH` in 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.

