@whitecat/bridge

Local CLI bridge for Whitecat — lets you use your own claude, codex, or gemini CLI from the Whitecat cloud app, without ever sending your conversations through someone else's API.

Why this exists

Whitecat runs in the cloud, but your AI CLI runs on your machine. The browser cannot spawn local processes for security reasons. This tiny daemon bridges the two: Whitecat → your browser → localhost:7117 → your CLI.

[whitecat.qualcosarandom.win]
            │
        HTTPS │ chat / brief / workflow
            ▼
   ┌──────────────────────┐
   │   Your browser       │
   └──────────┬───────────┘
              │ fetch(localhost:7117)
              ▼
   ┌──────────────────────┐
   │  whitecat-bridge     │  ← this package
   │  (your machine)      │
   └──────────┬───────────┘
              │ spawn
              ▼
   [ claude | codex | gemini ]

Install & run

npx @whitecat/bridge

That's it. The first run prints a pairing token like:

Whitecat bridge listening on http://127.0.0.1:7117
Pairing token: ws_aB3xK9mP4nLq7vRtY2eZ
Open Whitecat → Settings → Local CLI → paste the token.

Copy the token, paste it in Whitecat Settings, and you're done. From now on, every chat/brief/workflow call hits your local CLI for free.

Supported CLIs

| Provider | Binary | How to install | |---|---|---| | Claude | claude | npm install -g @anthropic-ai/claude-code then claude login | | Codex (OpenAI) | codex | npm install -g @openai/codex then codex login | | Gemini (Google) | gemini | npm install -g @google/gemini-cli then gemini (interactive auth) |

The bridge auto-detects which binaries you have installed. If a CLI isn't installed, the corresponding mode just isn't available — no errors.

Security

• The bridge listens only on 127.0.0.1 (localhost). It is not reachable from the internet.
• Every request must include the pairing token (HTTP header Authorization: Bearer <token>). Wrong/missing token → 401.
• CORS allow-list is strict: only the official Whitecat domain + localhost for dev are accepted.
• Token is regenerated each fresh start unless you set WHITECAT_BRIDGE_TOKEN.

Environment variables

| Variable | Default | Description | |---|---|---| | WHITECAT_BRIDGE_PORT | 7117 | Port to listen on | | WHITECAT_BRIDGE_TOKEN | (random) | Pin a stable token (otherwise regenerates each start) | | WHITECAT_BRIDGE_ALLOWED_ORIGINS | (built-in list) | Comma-separated extra origins for CORS | | WHITECAT_BRIDGE_LOG_LEVEL | info | debug / info / warn / error |

Development

git clone https://github.com/Mattialicciardi/whitecat.git
cd whitecat/packages/bridge
pnpm install
pnpm dev

License

MIT © Mattia Licciardi