# Set up Claude Code and Codex for the Nexus by AllCode AI proxy

These instructions are for a person or a coding agent (Claude Code, Codex) configuring **this
machine** to send Claude Code and Codex requests through the Nexus AI proxy at
`https://nexus-dev-proxy.allcode.com`. They contain no secret. Each machine gets its own key: the setup script makes it
when it runs. To configure by hand you need a key (`nxk_…`), which the person gets from the
**Manual setup** panel after signing in at `https://nexus-dev-proxy.allcode.com/login`.

Rules for agents:

- Never print, log or echo the key. When you report back, show at most its last four characters.
- Change only the values named here. Keep every other setting, comment and line of each file.
- Back up every file before changing it (`<file>.nexus-backup-<YYYYMMDD-HHMMSS>`).
- You may install what's missing, but **ask the person first**: say which components are missing
  and install only the ones they agree to, by passing the matching `--install` list to the setup
  script (below). If they decline, or you can't ask, pass `--no-install`. Never install anything
  another way, and never with `sudo` or as an administrator.
- If a step is unclear or a file can't be merged safely, stop and ask the person.

## The setup script

The quickest route is the setup script, which does all of the steps below and installs what the
person chose. There are two ways to get it:

- **The one-time command** from the sign-in page, after the person signs in at `https://nexus-dev-proxy.allcode.com/login`:
  `curl -fsSL https://nexus-dev-proxy.allcode.com/setup/<code> | sh`, or `irm https://nexus-dev-proxy.allcode.com/setup/<code>.ps1 | iex` on
  Windows. It carries a one-time code, not a key: the script trades the code for this machine's
  key when it runs, so it runs without the person. It works once, for 10 minutes. **Agents should
  prefer this one**: ask the person to sign in and paste you the command.
- **The code-less command**, the same for everyone: `curl -fsSL https://nexus-dev-proxy.allcode.com/setup/install.sh | sh`,
  or `irm https://nexus-dev-proxy.allcode.com/setup/install.ps1 | iex` on Windows. It holds no key: it opens the sign-in page
  and asks for the code the page then shows, so it needs **the person at a terminal**. Don't run it
  where they can't type.

To pass options: `curl -fsSL <command's URL> | sh -s -- --install claude,codex`; on Windows,
`$env:NEXUS_SETUP_ARGS = '--install claude,codex'` before `irm … | iex`.

**Components:** claude, codex, claude-desktop, codex-app, vscode (Claude Code, Codex, Claude
Desktop, the ChatGPT app, and the Claude Code extension of VS Code and its family: Insiders,
Cursor, Windsurf, VSCodium).

| Option | What it does |
|---|---|
| `--install LIST` | Install these when missing (a comma-separated list of components, or `all`) |
| `--no-install` | Install nothing; configure what is there |
| `--only LIST` | Set up only these components (`--claude-only` and `--codex-only` still work) |
| `--yes` | Accept every default without asking |
| `--dry-run` | Show the plan and the file changes; write and install nothing |
| `--strict` | Exit 1 if any step failed |

Without `--install` or `--no-install`, the script asks at a terminal, and with no terminal it
installs only the missing CLIs and the extensions of editors already there, never a desktop app.
Unknown options are warned about and ignored. Only the vendors' own installers run, over HTTPS
from their own hosts; nothing needs `sudo`, and nothing is overwritten or uninstalled.

**The summary:** the run never stops half-way. It ends with one row per component (found,
installed, configured, skipped, failed with a one-line reason and its fix, or a manual step)
and the key's name, its last four characters and the `https://nexus-dev-proxy.allcode.com/keys` link. Report the rows that
failed or need a manual step to the person.

**The exit code:**

- `0`: the run completed, whatever the individual steps did (read the summary).
- `3`: no usable key (the proxy refused it, the code was spent or expired, or sign-in was
  cancelled). Nothing was written: the person signs in again at `https://nexus-dev-proxy.allcode.com/login`.
- `1`: only with `--strict`, when a step failed.

The steps below are the same, by hand, for when the script can't run.

## 1. Which tools to configure

Configure each tool that is installed:

- **Claude Code** if `claude` is on the PATH or its configuration directory exists.
- **Codex** if `codex` is on the PATH or its configuration directory exists.
- If neither is found, configure both default locations.
- If the person asked for only one tool, configure only that one.

| | macOS / Linux | Windows |
|---|---|---|
| Claude Code settings | `~/.claude/settings.json` | `%USERPROFILE%\.claude\settings.json` |
| Codex configuration | `~/.codex/config.toml` | `%USERPROFILE%\.codex\config.toml` |

If `CLAUDE_CONFIG_DIR` is set, Claude Code's file is `$CLAUDE_CONFIG_DIR/settings.json`. If
`CODEX_HOME` is set, Codex's file is `$CODEX_HOME/config.toml`.

## 2. Claude Code: `settings.json`

Set exactly two entries in the `env` object, creating the file or the `env` object if missing:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://nexus-dev-proxy.allcode.com",
    "ANTHROPIC_AUTH_TOKEN": "<the nxk_ key>"
  }
}
```

- Merge: keep every other top-level key and every other `env` entry as they are. The file must stay
  valid JSON (no comments, no trailing commas).
- The base URL has **no** `/v1`. No model settings are needed: Claude Code's default and
  `/model opus`, `sonnet` and `haiku` work as they are.
- `env.ANTHROPIC_API_KEY`: if its value starts with `nxk_` it is an old Nexus key, so remove it.
  Otherwise leave it but tell the person it overrides the Nexus key.
- `env.ANTHROPIC_DEFAULT_OPUS_MODEL`, `…_SONNET_MODEL`, `…_HAIKU_MODEL`: if the old
  `ANTHROPIC_BASE_URL` was this proxy or the old `ANTHROPIC_AUTH_TOKEN` started with `nxk_`, these
  came from an earlier Nexus setup, so remove them. Otherwise leave them and tell the person.
- Tell the person (don't change) if `apiKeyHelper` is set, if `ANTHROPIC_API_KEY` is exported in
  their shell or shell profile, or if `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` is set:
  each would bypass or override the Nexus key.
- On macOS / Linux, make the file readable by its owner only: `chmod 600 ~/.claude/settings.json`.

## 3. Codex: `config.toml`

Two top-level keys, which must come **before the first `[table]`** line of the file:

```toml
model_provider = "nexus"
model = "<a model the proxy serves>"
```

- Replace an existing top-level `model_provider` line; add it if missing.
- Keep an existing top-level `model` if it is one of the models this proxy serves (listed at
  `https://nexus-dev-proxy.allcode.com/v1/models` with the key); otherwise set it to `<a model the proxy serves>`.

And this table, replacing any existing `[model_providers.nexus]` table and its sub-tables (such as
`[model_providers.nexus.auth]`) in place, or appended at the end of the file:

```toml
[model_providers.nexus]
name = "Nexus"
base_url = "https://nexus-dev-proxy.allcode.com/v1"
wire_api = "responses"
experimental_bearer_token = "<the nxk_ key>"
```

- Keep every other line of the file exactly as it was: other providers, profiles, comments, MCP
  servers and so on.
- The base URL **ends in `/v1`**. `experimental_bearer_token` must not be combined with `env_key`,
  `auth` or `requires_openai_auth` in the same table.
- Tell the person if a top-level `profile = …` is set: that profile may pick another provider.
- On macOS / Linux: `chmod 600 ~/.codex/config.toml`.

## 4. Only one of the tools

- **Claude Code only**: do step 2, skip step 3.
- **Codex only**: do step 3, skip step 2.
- **Both** (one key serves both tools): do steps 2 and 3 with the same key.

## 5. Verify

Ask the proxy for its model list with the key; HTTP 200 means the key works:

```sh
# macOS / Linux (keep the key off the command line: read it from a file or a variable)
curl -sS -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $NEXUS_KEY" https://nexus-dev-proxy.allcode.com/v1/models
```

```powershell
# Windows PowerShell
(Invoke-WebRequest -UseBasicParsing https://nexus-dev-proxy.allcode.com/v1/models -Headers @{ Authorization = "Bearer $key" }).StatusCode
```

A 401 means the key was revoked or replaced by a newer setup of this machine: the person signs
in again at `https://nexus-dev-proxy.allcode.com/login`. Then check each tool from a new terminal:

```sh
claude -p "reply ok"
codex exec --skip-git-repo-check "reply ok"
```

Running Claude Code or Codex sessions only pick up the change when restarted.

## 6. Restore a backup

Each changed file has a copy next to it named `<file>.nexus-backup-<timestamp>`. To undo, copy
the newest backup back over the file:

```sh
cp ~/.claude/settings.json.nexus-backup-20260101-120000 ~/.claude/settings.json
cp ~/.codex/config.toml.nexus-backup-20260101-120000 ~/.codex/config.toml
```

```powershell
Copy-Item "$env:USERPROFILE\.claude\settings.json.nexus-backup-20260101-120000" "$env:USERPROFILE\.claude\settings.json"
```

A file that did not exist before has no backup: delete it to undo.

## About the key

The key is personal and belongs to this machine: never commit it or put it in a shared or managed
settings file. Unless your organisation set a lifetime, it doesn't expire; your admin can revoke
it. Setting the same machine up again replaces its key (the previous one stops working); other
machines keep theirs. The person sees and revokes their keys at `https://nexus-dev-proxy.allcode.com/keys`.