One key. Ten harnesses. Use Fireworks AI models inside the coding tools you already love: Claude Code, Claude Desktop, OpenCode, Codex, Pi, Cursor, VS Code, GitHub Copilot (app and CLI), and DeepSeek Harness.
Nexus CLI points each harness at Fireworks by editing that harness's own settings. No hosted service to deploy. Claude Desktop is the one exception: it runs a tiny local shim (a launchd/systemd user unit) and is covered under Claude Desktop.
nexus <harness>routes it through Fireworks and registers Fireworks models in its picker.nexus <harness> offputs your original settings back exactly as they were, byte for byte.- One Fireworks key is stored once (OS keychain where available) and shared by every harness you connect.
Only works on this computer. Nexus CLI changes the settings of harnesses running on the machine where you run it. Cloud and remote agents (for example Cursor background agents, Claude Code on the web, or Copilot coding agent) run on someone else's machine, never read those settings, and aren't supported — even when you're signed in to the same account.
Contents: Quick start · Supported harnesses · Default models · Claude Code · Codex · OpenCode · Pi · Cursor · VS Code Chat · GitHub Copilot app · GitHub Copilot CLI · DeepSeek Harness · Claude Desktop · Nexus Auto · Models · Azure / Foundry · CLI reference · Keys and storage · Troubleshooting · Update and uninstall
1. Install
curl -fsSL https://nexus.fireworks.ai/install.sh | bashOr install direct from GitHub:
curl -fsSL https://raw.githubusercontent.com/fw-ai/nexus-cli/main/install.sh | bash2. Sign in
nexus login # browser sign-in, or paste a fw_… key3. Connect a harness
nexus claude # routes through Fireworks, appends the catalog to /model✓ Claude Code → Fireworks · auto
Only works on this computer. Cloud and remote agents aren't supported.
Model picker
Anthropic model slots → unchanged
Fireworks catalog → appended in /model
Also in your model list:
deepseek-flash-latest, ember-1, glm-fast-latest, …
Restart Claude Code to use the new setup.
Manage models
Browse nexus model list
Choose model nexus claude --model <id>
4. Restart the harness, then check
nexus claude statusClaude Code
Connection: on
Provider: Fireworks
Auth: X-Fireworks-Api-Key header in settings.json
Model: auto
Registered models:
auto
deepseek-flash-latest
...
5. Make it yours
nexus model list # browse the models you can pick
nexus claude --model glm-latest # choose one (or pin tiers: --sonnet <id>)
nexus status # every harness: on/off and installed
nexus claude off # back to exactly how things wereUse any harness name in place of claude: claude-desktop, opencode, codex (or chatgpt),
pi, cursor, vscode, copilot-app, copilot-cli, deepseek. Start with nexus help, then use nexus <harness> help or nexus <command> --help for options.
- You need bash, git, and Node.js 22+. If Node is missing or too old, the installer offers to install Node via Homebrew on macOS (asks first), or points you to nvm / nodejs.org / NodeSource elsewhere.
- The installer puts the CLI in
~/.nexus/cli, adds thenexuslauncher to~/.local/binand your shellPATH, and runs the same cleanup asnexus update. It does not sign you in or change harness settings — that's steps 2 and 3. - Windows: run the install from Git Bash. Piping it through PowerShell breaks line endings (
set: pipefail\r).
From an SSH checkout:
tmp="$(mktemp -d)" && git clone --depth 1 git@github.com:fw-ai/nexus-cli.git "$tmp" \
&& NEXUS_SOURCE=git@github.com:fw-ai/nexus-cli.git bash < "$tmp/install.sh"Run nexus status to see this list along with which harnesses are connected and installed on your machine.
Every harness supports on, off, status, and help, and every model change goes through
<harness> on. Settings apply per session: restart the harness (or start a new session) after on/off.
| Harness | Command | Settings it edits | Quit / restart |
|---|---|---|---|
| Claude Code | nexus claude |
~/.claude/settings.json |
Restart after |
| Codex | nexus codex / nexus chatgpt |
~/.codex/config.toml |
Restart after |
| OpenCode | nexus opencode |
~/.config/opencode/opencode.json |
Restart after |
| Pi | nexus pi |
~/.pi/agent/{settings,models,auth}.json |
Restart after |
| Cursor | nexus cursor |
state.vscdb (SQLite) |
Quit Cursor first |
| VS Code Chat | nexus vscode |
chatLanguageModels.json + state.vscdb |
Quit VS Code first |
| GitHub Copilot app | nexus copilot-app |
~/.copilot/data.db (SQLite) |
Quit Copilot first |
| GitHub Copilot CLI | nexus copilot-cli |
~/.copilot/providers.json + settings.json |
Restart copilot after |
| DeepSeek Harness | nexus deepseek |
~/.dsh/settings.yaml + patch layers |
Restart dsh after |
| Claude Desktop (Limited) | nexus claude-desktop |
Claude-3p provider profile + loopback shim | Quit and reopen Desktop after |
off restores from a snapshot kept under ~/.nexus/ (files) or removes exactly what Nexus CLI
added (IDEs and databases). Your own providers, models, and settings are never touched.
on refuses a harness that isn't installed. Any sign of the tool counts: its command, its app, its editor
extension, or data only the tool writes (like Claude Code's ~/.claude/projects). If the tool is installed
somewhere Nexus CLI doesn't look, pass --skip-install-check. nexus status shows which harnesses are installed
(--json for scripts).
Every harness's main model starts on auto, Fireworks' smart router: it automatically
picks the best model for the task, so everything works with zero configuration. Pin a
concrete model whenever you want one model for every turn. Claude Code's tier slots and
Claude Desktop's per-family defaults are detailed in their sections.
nexus model list # what you can pick (prices included)
nexus <harness> --model glm-latest # pin one model
nexus <harness> # re-run to refresh the picker; your pick stays| Harness | Default | Notes |
|---|---|---|
Claude Code tiers (opus/sonnet/haiku/fable/subagents) |
Claude's own defaults | Pin with --opus / --sonnet / --haiku / --fable / --subagent; native unpins |
Claude /model picker |
Serverless catalog appended | --model <id> selects a row and ensures it's listed |
| Everything else | auto |
Codex signs in with ChatGPT for GPT turns (details) |
Re-running nexus <harness> refreshes the registered catalog (new models added, retired
ones pruned, metadata re-rendered) and keeps your pick — with one exception: a retired-router
pick (FireRouter, auto-instant) moves to auto. Both routers are retired; selecting them
is rejected in favour of auto (see Nexus Auto).
nexus claude # connect; catalog lands in /model
nexus claude --model <id> # select a model and ensure it's in /model
nexus claude --sonnet <id> --subagent <id> # pin tier slots (native unpins)
nexus claude status # mapping, auth, and per-slot rates (--json for scripts)
nexus claude usage # live session meter at Fireworks rates
nexus claude demo # race two models on a prompt (needs routing on)
nexus claude offHow it routes. Nexus CLI appends the Fireworks catalog to /model and leaves the Anthropic
tier slots on Claude's own defaults unless you pin them. Auth is a static
X-Fireworks-Api-Key header in settings.json (owner-only file; the OS keychain stays the
source of truth), which wins over any stray ANTHROPIC_API_KEY, so a leftover key can't
quietly break routing. An exact backup is kept for off.
Notes that matter:
- Costs shown in Claude Code are not your bill. Claude Code estimates at Anthropic list
prices; Fireworks bills at serverless rates. Trust
nexus claude status,nexus model list, and the billing dashboard. The optional status line shows per-model cost at Fireworks rates. [1m]tags are normal. Picker rows for 1M-context models carry a[1m]suffix so Claude Code sizes the window correctly; it strips the tag before sending. Other harnesses use the bare name.- Text-only models + images can break a session.
nexus claude statusmarks each modelvisionortext-only; recover a broken session with/rewind. - Native
WebSearch/WebFetchkeep working through the gateway; your own MCPs and permission rules are untouched. - Claude Code's telemetry stays on. Nexus CLI doesn't set
DISABLE_TELEMETRY,DO_NOT_TRACK, orCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: any of them stops Claude Code from loading its feature flags, which hides tools such as Artifact. If you set one yourself insettings.jsonwhile connected, Nexus CLI leaves it alone.
on adds a statusLine (only if you don't already have one) showing which model served
each call and what it cost at Fireworks rates:
━━━━━━━━━━━━ ━ ━ · $70.39 · routed model: Claude Opus 5
━ Claude Opus 5 $62.91 98% cache · ━ GLM 5.2 $7.35 96% cache · ━ DeepSeek V4 Flash $0.13 87% cache
It reads the session transcript, so mid-session model switches are priced by the model that
actually served each call. off removes it; NO_COLOR gives plain text.
Sends OpenAI Codex CLI (and the ChatGPT desktop app,
which shares ~/.codex) through Fireworks via the Responses API.
nexus codex # writes ~/.codex/config.toml (auto, ChatGPT sign-in)
nexus codex status
nexus codex --model glm-latest # switch model
nexus codex offCodex keeps its own sign-in. The first nexus codex selects auto and sets
requires_openai_auth = true, so Codex asks you to sign in (codex login) and sends that
sign-in with each request; your Fireworks key rides in its own x-fireworks-api-key header.
GPT turns are paid by, in order:
- Codex's sign-in — your ChatGPT plan, or the OpenAI key you signed in with
(
codex login --with-api-key; no browser:codex login --device-auth, ornexus key export --openai | codex login --with-api-key). - An OpenAI Provider Key on your Fireworks account (Provider Keys).
With neither, GPT models fail but auto keeps working on open models. The /model picker
lists stock Codex's GPT models first (read with codex debug models, so new ones appear as
Codex offers them), then the Fireworks catalog. A re-run keeps the model you're on.
Notes that matter:
- Threads keep the provider they started on. ChatGPT app threads started on OpenAI stay
on OpenAI; start a new thread for Fireworks. Resuming a CLI session needs the provider on:
codex resume <id> -c model_provider="fireworks-ai". - MiniMax doesn't work on Codex (its templates reject Codex's message shape);
nexus codex --model minimax-latestexplains the Responses-API problem. Use a Chat Completions harness instead. - Quit the ChatGPT app before
on/off(it caches config at boot), like the IDEs;--forcewrites anyway, not recommended.nexus chatgptis the same command.
Adds a provider.fireworks-ai block to ~/.config/opencode/opencode.json, sets the default
model, and registers the preferred catalog for /model (skipping models OpenCode already
lists from models.dev, so nothing shows twice). Your key is saved in the file (owner-only).
OpenCode v2's providers map is written too when present. Offline, it falls back to the
active model. --config-path <path> for a config elsewhere.
nexus opencode
nexus opencode --model glm-latest
nexus opencode offSets defaultProvider/defaultModel in ~/.pi/agent/settings.json, registers the catalog
(full accounts/fireworks/... IDs, so rows line up with Pi's own) in models.json, and saves
your key in auth.json. All three files are snapshot-backed; off restores them byte-for-byte, with a surgical fallback that removes only what Nexus CLI added if you edited a file while connected.
--settings-path <path> for a settings file elsewhere.
nexus pi
nexus pi --model glm-latest
nexus pi offQuit Cursor (
Cmd-Q) beforeonoroff— a running Cursor overwrites your edit from memory. Nexus CLI waits in the terminal, offers to continue after ~90s, and--forceskips the wait.
Nexus CLI writes Cursor's state.vscdb directly: your key goes to its secure storage, the base
URL points at Fireworks, and Fireworks models are registered per mode. --model <id> applies
to every mode you already have (it never invents modes). While connected, only Fireworks
models answer — Cursor's built-ins are hidden until nexus cursor off, which removes only
what Nexus CLI added. --db-path <path> for a non-default database (e.g. Insiders).
nexus cursor
nexus cursor --model glm-fast-latest
nexus cursor offQuit VS Code before
onoroff, same rule as Cursor.
Adds a Fireworks provider to chatLanguageModels.json; your key is not in that file —
it lives encrypted (Electron safeStorage) in VS Code's state.vscdb under a
chat.lm.secret.fw-* id. On Linux that needs libsecret for real encryption (Nexus CLI writes
either way, with a warning). off restores the JSON exactly and deletes the secret row;
providers you set up yourself are untouched. --vscode-path <path> for a non-default file.
nexus vscode
nexus vscode --model deepseek-flash-latest
nexus vscode offAdds one fc- provider (with its model rows) to the desktop app's ~/.copilot/data.db;
your key rides as an Authorization header on that row (the file is owner-only). Your
built-in Copilot models keep working alongside it, and off deletes exactly Nexus CLI's rows.
BYOK models in the app don't get image input, the hover Context row, or AI-credits pricing.
Quit GitHub Copilot before
onoroff, same rule as Cursor.
nexus copilot-app
nexus copilot-app --model glm-latest
nexus copilot-app offRoutes the copilot command through Fireworks with plain JSON: a fireworks provider plus
one row per model in ~/.copilot/providers.json, and the selected model in settings.json
(a BYOK provider has no default, and the CLI won't start without one). Pick models with
the provider attached — copilot --model fireworks/glm-latest or /model; a bare name is
rejected and quietly falls back. Per-model image input is supported; context/reasoning/pricing
aren't shown for BYOK models. off restores providers.json from its snapshot and keeps
anything you added yourself. The desktop app and the CLI share a folder but no settings —
turn on either, both, or neither.
nexus copilot-cli
nexus copilot-cli --model glm-latest
nexus copilot-cli offSends DeepSeek Harness (dsh) through
Fireworks: writes the fireworks provider and default model into ~/.dsh/settings.yaml
plus the cordis.patch.yml layers dsh composes over it, and saves your key as
FIREWORKS_API_KEY in ~/.dsh/.credentials.yaml (owner-only). --config-path <path> for a
settings.yaml elsewhere (credentials stay next to that file).
nexus deepseek
nexus deepseek --model glm-latest
nexus deepseek offLimited: while Nexus is on, Claude Desktop opens a new local workspace without your chats, and each imported connector needs a one-time re-auth. To return to your main workspace, run
nexus claude-desktop offand reopen Claude Desktop. Nothing is lost. For the fullest experience, use Claude Code, Codex, or the ChatGPT desktop app.
Runs Claude Desktop's Chat, Cowork, and Code surfaces on Fireworks models, with the
Fireworks line-up and per-model effort menus in the picker. Family defaults start on
auto for Opus and Fable, glm-latest for Sonnet, and glm-flash-latest for Haiku.
nexus claude-desktop on # switch Desktop to Fireworks; imports your connectors
nexus claude-desktop on --model <id> # add a serverless model to the picker
nexus claude-desktop mcp sync # re-import connectors you've added since
nexus claude-desktop off # restore your previous setupQuit and reopen Desktop after on/off. Requires macOS or Linux and a stored credential
(nexus login). Linux is unofficial: Anthropic documents Desktop's third-party mode for
macOS and Windows only, but the Linux build ships the same mechanism and Nexus CLI drives it
the same way.
How it works. on writes a third-party inference provider profile (Desktop's own
mechanism) pointing at a small loopback shim service (launchd on macOS, systemd user unit
on Linux) that maps model names and mirrors the model catalog. The shim auto-starts at
login; if it's ever down, nexus claude-desktop status says so and on brings it back. On
Linux, on needs a systemd user session (the normal case when logged in).
Connectors are managed through Nexus CLI — Desktop's in-app connector browser is suppressed in third-party mode:
onimports connectors from your session history, previous Desktop config, and claude.ai org registry. Each needs a one-time re-auth the first time you use it.mcp syncre-imports;mcp add <name> <url>/mcp remove <name>manage entries by hand. Your connector setup survivesoff/on.- Google connectors (Gmail, Drive, Calendar, BigQuery) and Figma can't self-register:
register your own OAuth client once, e.g.
nexus claude-desktop mcp add gmail https://gmailmcp.googleapis.com/mcp/v1 --client-id "<ID>.apps.googleusercontent.com" --client-secret "GOCSPX-..."(a value travels in shell history, so treat with care), or use Figma's local server:nexus claude-desktop mcp add figma-desktop http://127.0.0.1:3845/mcp.
What changes in third-party mode (Claude Desktop's rules, not Nexus CLI bugs):
| Change | Workaround |
|---|---|
| In-app connector browser / one-click add is gone | mcp sync / mcp add |
| Connectors relying on your claude.ai sign-in need an OAuth client | Google/Figma recipes above |
| Chat, Cowork and Code use the Fireworks picker, not your claude.ai subscription models | off restores them |
Third-party mode does not show your claude.ai chats, projects, artifacts, memory, or scheduled tasks. Nothing is deleted, and off brings them back. |
Recreate what you need while connected |
| New chats, projects, artifacts, and memory are saved only on this computer. They don't appear on claude.ai web or mobile and can't be shared. | Run off to share or work on the web |
Skills and plugins are copied over on on. Run on again to copy ones you add later. |
Re-run nexus claude-desktop on |
Cowork and Chat can reach any website. To limit that, set Allowed egress hosts in Developer → Configure Third-Party Inference; on keeps your list. |
Third-party mode blocks all hosts when the list is unset, so on writes coworkEgressAllowedHosts: ["*"] |
| Scheduled tasks run only while the computer is awake; Chat has no past-chat search; voice mode is unavailable | off restores them |
Anthropic's own summary: third-party feature matrix.
If status shows the shim NOT RESPONDING, run nexus claude-desktop on to restart it.
FireRouter is now Nexus Auto, model ID auto: one model ID that picks a Fireworks open
model or an Anthropic or OpenAI model for each user turn. FireRouter routes such as
firerouter and firerouter/opus, and the latency-first auto-instant, are retired as
model selections. auto is the main default across harnesses; Claude Code tier slots
and Claude Desktop family defaults keep the exceptions described in their sections.
Selecting one fails, on every harness (including Claude tier-slot flags):
✗ Error: --model firerouter is no longer supported. Use --model auto instead. Run: nexus claude help
Nothing is written and no key is stored. The replacement named in the error is flag-specific (for example, --sonnet firerouter says to use --sonnet auto). You can also name a concrete model from nexus model list.
Already on one? Upgrading moves a stored FireRouter selection to auto on every
harness, re-running nexus <harness> does the same, and retired picker rows leave with it.
status and off still read a stored config, so nothing breaks before you upgrade.
Nexus Auto uses an Anthropic or OpenAI model only when a credential for it reaches the
request. Save your own keys once with nexus auto; Nexus CLI sends each one from every harness
that can carry it and has no credentials of its own for that provider:
nexus auto --anthropic-api-key # prompts for the key; saved to ~/.nexus/config.json
nexus auto --openai-api-key # prompts for the key
nexus opencode # run each harness again to apply
nexus auto # shows which keys are saved
nexus auto --unset openai-api-key # clear it here and in every harness| Harness | Anthropic turns | OpenAI turns |
|---|---|---|
| Claude Code (and Claude Agent SDK via Claude Code settings) | Claude Code's own sign-in (claude login, or ANTHROPIC_API_KEY) |
Saved key |
| Codex, ChatGPT desktop app | Saved key | Codex's own sign-in |
| OpenCode, Pi, VS Code, Copilot CLI, DeepSeek Harness | Saved key | Saved key |
| Claude Desktop | Saved key, sent live by the local shim | Saved key, sent live by the local shim |
| Cursor, Copilot app | Provider Key | Provider Key |
A Provider Key on your Fireworks account works in every harness, with nothing stored locally.
- A saved key only fills a gap: Claude Code never gets the Anthropic key (its login covers Claude turns), and Codex never gets the OpenAI key (its sign-in covers GPT turns).
- Nexus CLI writes a saved key into the harness config as an
x-anthropic-api-keyorx-openai-api-keyheader (files are mode0600). VS Code gets it on theautorow only. Claude Desktop's shim adds it to auto turns on the next request; afternexus update, the shim restarts so code updates take effect without a re-run. - While
nexus auto --providers fireworksis set, saved keys stay saved but no harness gets them: the nextnexus <harness>removes them, andnexus auto --resetfollowed bynexus <harness>sends them again. - Nexus CLI never sends
ANTHROPIC_API_KEYorOPENAI_API_KEYfrom your environment, so a key exported for another tool never starts billing Anthropic or OpenAI. A harness can still read its own variable: Claude Code usesANTHROPIC_API_KEY, Codex signs in with an OpenAI key. <harness> ondoesn't take--anthropic-api-key/--openai-api-key; it points you tonexus auto.nexus configure --anthropic-api-key/--openai-api-key/--unsetstill work but are deprecated.
The old
--routerflag is gone. Use--model auto.--routing-preferenceis deprecated and has no effect.
FireRouter as a gateway product: FireRouter overview.
nexus model list # browse (alias: nexus models)
nexus model list --search glm
nexus model list --refresh # skip the 1-hour cache
nexus model list --jsonLists coding-ready serverless models plus the -latest router aliases
(glm-latest, kimi-fast-latest, minimax-latest, …). Prefer the aliases over pinned
versions — they follow new releases on their own. Results are cached for 1 hour;
offline, the last cached list is shown instead of an error. Retired routers never appear
(see Nexus Auto).
Short names everywhere. glm-latest and full accounts/fireworks/... IDs both work;
harnesses store the form they use themselves (Pi stores full IDs, most others short names).
US-only routers take short names too, when a US router appears in your account's catalog (see US-only Serverless). Check with nexus model list:
nexus claude on --model kimi-k3-us
nexus opencode on --model glm-5p3-flash-usWhich key is used, in order: --api-key → FIREWORKS_API_KEY → saved key. For rates,
nexus model list and nexus claude status show Fireworks serverless pricing — not the
Anthropic list prices Claude Code displays (see Pricing estimates).
Claude Code's picker and session estimates use Anthropic list prices, while Fireworks
bills at serverless rates, so the in-app number can look much higher than your real bill.
Trust nexus claude status, nexus model list, and the
billing dashboard.
Fireworks models are also first-party models inside Microsoft Foundry, billed through Azure. Foundry speaks an OpenAI-compatible API, so OpenCode, Pi, Cursor, and VS Code can point there instead of the Fireworks gateway (Claude Code and Codex can't — neither speaks Foundry's transport).
nexus configure --provider azure \
--base-url https://<resource>.services.ai.azure.com \
--api-key <azure-api-key>
nexus opencode # goes through your Foundry endpoint- Endpoint. Whatever you paste (resource root, portal project endpoint,
/modelsroute) is tidied intohttps://<resource>.services.ai.azure.com/openai/v1. Find it under Project settings in the Foundry portal. - Auth. Your Azure key (not
fw_), saved as-is or as an$AZURE_API_KEYreference. - Model. Your Foundry deployment name (the catalog name without the
fireworks-ai/prefix, e.g.FW-GLM-5.2). Defaults toFW-GLM-5.2; pick per run with--model, or per command with--azure --base-url …. - Each harness gets its own
fireworks-azureprovider;offrestores exactly, andnexus configure --provider fireworksswitches back.model listdoesn't apply in Azure mode.
| Harness | Provider |
|---|---|
| OpenCode | provider.fireworks-azure in opencode.json |
| Pi | custom openai-completions provider in models.json |
| Cursor | OpenAI-compatible URL, deployment, and key in state.vscdb |
| VS Code | custom endpoint model in chatLanguageModels.json; key in safeStorage |
Harness-first: nexus <harness> <command>, plus a few global commands.
nexus <harness> with no command runs on.
Per harness (claude, claude-desktop, opencode, codex / chatgpt, pi, cursor, vscode, copilot-app, copilot-cli, deepseek)
nexus <harness> on Send the harness through Fireworks (the default when no command given).
nexus <harness> off Bring back your previous provider/config.
nexus <harness> status Show the provider, auth, and model mapping.
nexus <harness> status --json Same state as JSON (for CI checks).
nexus <harness> help Help for that harness.
keyCurrent in nexus status --json says whether a harness that's on sends your stored Fireworks key: true (it holds that key, or fetches it per request through Nexus, like Claude Code's nexus key export helper), false (it still holds a different Fireworks key, e.g. after switching accounts; run nexus <harness> on again), or null (off, no key, a $FIREWORKS_API_KEY reference whose value Nexus doesn't control, or a copy that can only be read through a keychain prompt, which status never triggers). Keys are compared in memory and never printed.
Claude adds nexus claude usage and nexus claude demo. A few plumbing commands also exist but stay out of the main flow: nexus key export (print a stored key), nexus claude-desktop mcp list|add|remove|sync, and nexus claude demo clean.
Global
nexus login Sign in: browser (creates a key) or paste a key you have.
nexus logout Clear the stored key (keychain entry + config ref).
nexus status Show sign-in state, environment, key storage, and each harness (on/off, installed).
nexus status --json Same as JSON. Each `perHarness` entry has `id`, `enabled`, `installed`, and `keyCurrent`.
nexus model list Browse the serverless catalog (`models` is an alias).
nexus configure Set the provider (Azure/Foundry).
nexus auto Show the auto router's provider scope and saved keys.
nexus auto --anthropic-api-key Prompt to save an Anthropic key for Nexus Auto (`--openai-api-key` for OpenAI).
nexus auto --unset openai-api-key Clear a saved key here and in every harness.
nexus auto --providers fireworks Route auto only to Fireworks-hosted models, then run `nexus <harness>` again.
nexus auto --reset Back to the default scope.
nexus update Update Nexus CLI (`upgrade` is an alias).
nexus uninstall Switch off + restore every harness, then remove Nexus CLI.
nexus --version Print the installed CLI version (-V; --json for machine-readable).
nexus help Show help (`help <topic>` or `<harness> help`).
Plumbing (used by recipes and CI): nexus key export [--openai | --anthropic] [--stored-only],
nexus claude-desktop mcp list|add|remove|sync, and nexus claude demo clean. Use nexus <harness> help
or a command's --help for options.
nexus auto narrows the auto router globally (not per harness): with nothing saved it
auto-selects based on your setup; --providers fireworks restricts it to Fireworks-hosted
models (the only provider today). Run nexus <harness> again per harness to apply it.
Your account's model restrictions always apply first.
- Your Fireworks key is never stored literally in
~/.nexus/config.json: that file holds a reference ({keychain:fireworks-api-key}). The key lives in the OS keychain, or an encrypted-file/plaintext fallback when no secret service exists (nexus statussays which). Saved Anthropic/OpenAI Auto keys (and an Azure key you provide directly, rather than as an$AZURE_API_KEYreference) are the exception: they live literally in the same owner-only file (mode0600). logincreates a machine key in the browser or checks a pasted one live;--pasteskips the question,--with-tokenreads stdin (CI),--account <id>targets enterprise SSO. On success it re-saves the key into every connected harness that keeps its own copy, so a rotated key reaches all of them.logoutcan also revoke the machine key server-side.- Some harness configs hold their own copy of the key (Claude's header, Codex, OpenCode, Pi,
DeepSeek); Cursor and VS Code use IDE
safeStorage. Files that hold keys are owner-only. nexus auto --unset <key>clears a saved Anthropic/OpenAI key and removes it from every harness that stored a copy (Claude Code keeps an Anthropic key it signs in with).--home <path>overrides HOME for config lookup.--data-dir <path>moves the backup/state folder, but only on harnesses that take it (Claude Code, OpenCode, Codex/chatgpt, Pi, Copilot CLI, and DeepSeek). Handy for sandboxes and tests.
FIREWORKS_API_KEY interaction. When it's set, login uses it without copying it into
secret storage, and combining login with a key-saving option fails before changing
anything. Unset it first. <harness> on may still read, save, and bake it into a config.
| Symptom | Fix |
|---|---|
| Harness still uses the old model or provider | Fully restart the harness (Claude Code: exit and claude --resume <id>). Settings apply per session. |
| Cursor / VS Code / Copilot changes don't stick | Quit the app (Cmd-Q) before on/off; a running app saves over your edit. |
| Only Fireworks models answer in Cursor | Expected while connected. nexus cursor off brings back built-ins. |
--model firerouter… or --model auto-instant is rejected |
Both routers are retired. Use --model auto (or a concrete model from nexus model list). |
A picker or config still shows firerouter |
Re-run nexus <harness> (or nexus update): the selection moves to auto and retired rows are dropped. |
| Claude Code shows a scary cost estimate | It uses Anthropic list prices. Check nexus claude status for Fireworks rates. |
| Claude session breaks after pasting an image | A text-only model was active. /rewind, then pick a vision model. |
| A harness gets 401s after you rotated your key | Run nexus login — it re-saves the new key everywhere. Quit VS Code first. |
login fails with a key-storage conflict |
FIREWORKS_API_KEY is set. Unset it so Nexus CLI can store a key. |
| ChatGPT app thread ignores Fireworks models | Threads keep the provider they started on. Start a new thread (see Codex). |
Codex or the ChatGPT app says duplicate key in config.toml |
Quit the app, then run nexus update (or nexus codex on): it keeps the newest Fireworks headers and removes the stale copy. |
| Something else | nexus status shows sign-in, environment, storage, and whether each harness is on and installed. |
Claude Code can't tell which models see images, so pasting an image on a text-only model can
break the session. nexus claude status marks every model vision or text-only, and
adding a text-only model with --model prints a one-line warning. Recover with /rewind.
nexus update # or re-run the installer
nexus uninstall # restores every harness, then removes ~/.nexus and the launcher
nexus uninstall --force # no questions (CI / scripts)Upgrades leave your settings alone apart from re-saving keys and small forward migrations
(VS Code's provider apiType, Claude's ENABLE_TOOL_SEARCH, removing the Claude telemetry
opt-outs older versions set, catalog refresh in each
picker, Codex's sign-in mode, and moving retired-router selections to auto). The final
step runs in a fresh process, so migrations come from the new version.
Coming from FireConnect (pre-0.10.0)? Re-run the installer above once: it replaces the
old command with nexus, moves ~/.fireconnect to ~/.nexus, and keeps your harnesses,
key, and settings. From then on every command is nexus — and rename any FIRECONNECT_*
variables to NEXUS_*. Upgrading from
before 0.9.0 with Claude connected asks before briefly restoring your original settings,
then tells you to reconnect with nexus claude.