Connect
Connect CLI
Wire Claude Code, Codex, pi, Cursor, opencode and more to Token Harbor in one command — and cleanly restore everything.
Connect CLI
tokenharbor is a tiny command-line tool that points the AI coding agents you
already use at the Token Harbor gateway — one key, every model. It writes each
agent's native config for you (no base-URL or key wrangling), backs up
whatever was there before, and can restore your original setup at any time.
Install
One command. Nothing to install first — if your machine doesn't have Node.js,
a private copy is provisioned automatically into ~/.tokenharbor (your system
is never touched).
macOS / Linux
curl -fsSL https://tokenharbor.ai/connect.sh | sh
Windows (PowerShell)
irm https://tokenharbor.ai/connect.ps1 | iex
New to the terminal? On a Mac press <kbd>⌘ Space</kbd>, type "Terminal", hit Enter, then paste the command. On Windows, search "PowerShell".
After installing, the interactive menu opens automatically. Later, just run
tokenharbor in any new terminal to get it back.
The menu
[1] Connect ALL detected agents
[2] Pick agents one by one
[3] Restore original configs (undo everything, from backup)
[4] Status & diagnosis
[5] Change API key
[q] Quit
- [1] / [2] ask for your API key once (get one at /dashboard/api-keys — free account works), verify it, then configure the agents.
- [3] puts every agent back exactly the way it was before you connected —
previous values are recorded at connect time and a one-time
<file>.th-backupcopy sits next to every file we touch. - [5] swaps in a new key and re-applies it to everything already connected.
Supported agents
| Agent | Mode | What happens |
|---|---|---|
| Claude Code | auto | Writes ~/.claude/settings.json env (base URL + key) |
| Codex CLI | auto | Adds a tokenharbor provider to ~/.codex/config.toml |
| opencode | auto | Adds a provider to ~/.config/opencode/opencode.json |
| Continue | auto | Adds a "Token Harbor" model entry (config.json) |
| Aider | auto | Via the universal environment (OPENAI_API_BASE) |
| Cursor | guided | Prints the exact Base URL + your key to paste |
| Cline / Roo Code | guided | Prints the exact values for its settings |
| Windsurf | guided | Prints the exact values for its settings |
| Zed | guided | Prints the exact values for its settings |
| Cherry Studio | guided | Prints the exact values for its settings |
| OpenClaw | auto | Adds a provider + model allowlist to ~/.openclaw/openclaw.json |
| Hermes (Nous) | auto | Via the universal environment (OPENAI_BASE_URL) |
| Qwen Code | auto | Via the universal environment (+ set OPENAI_MODEL) |
| pi | auto | Adds a tokenharbor provider to ~/.pi/agent/models.json |
| Goose (Block) | guided | goose configure values printed |
| Crush (Charm) | guided | Prints the exact values for its provider setup |
| n8n | guided | Exact values for an OpenAI credential |
| Dify | guided | Exact values for an OpenAI-API-compatible provider |
| OpenHands | guided | Exact values for its LLM settings |
| Flowise | guided | Exact credential + BasePath values |
| Langflow | guided | Exact OpenAI-component values |
| ChatBox / LobeChat | guided | Exact custom-provider values |
Guided agents keep their API settings inside app-internal storage that no external tool can safely write — the CLI prints the exact two values to paste (including your actual key), which takes about 30 seconds.
Most other terminal tools work automatically through the universal
environment (OPENAI_* / ANTHROPIC_* variables, loaded by new terminals).
Commands
| Command | What it does |
|---|---|
tokenharbor | Open the interactive menu |
tokenharbor connect [agent…] | Configure detected agents (or only the named ones) |
tokenharbor disconnect [agent…] | Revert agents (or all), restoring prior values |
tokenharbor status | Key (masked), gateway reachability, connected + detected agents |
tokenharbor models | List the models your key can use |
tokenharbor doctor | Diagnose key / gateway / config files |
Flags for scripting: --key thk_…, --yes (non-interactive),
--skip-verify (behind proxies), --no-env (agent configs only),
--env-all (also override an existing OPENAI_API_KEY / ANTHROPIC_*).
Safety
- Reversible.
disconnect(or menu [3]) restores the values that were there before — not just deletion. - Non-destructive. A config file that fails to parse is never modified;
every file we do touch gets a one-time
.th-backupcopy first. - No hijacking. If you already export your own
OPENAI_API_KEY, the CLI leaves that variable group untouched by default so your other scripts keep billing where they did. - Local only. Your key lives in
~/.tokenharbor/config.json(mode 0600) and the agents' own configs — it is never sent anywhere except the Token Harbor gateway.
Troubleshooting
- "Could not reach the gateway" but your network is fine — corporate/VPN
proxies: Node's fetch ignores
HTTP_PROXY, so verification can false-negative. Answeryto "Configure anyway", or use--skip-verify. - "That doesn't look like a Token Harbor key" — keys start with
thk_. An OpenAIsk-…key won't work here; create one at /dashboard/api-keys. - Agent doesn't pick up the change — open a new terminal (the environment loads on shell start), or restart the editor for GUI agents.
Uninstall
Menu [3] (or tokenharbor disconnect) restores every agent and removes the
shell hook. Then delete the tool itself:
rm -rf ~/.tokenharbor