CH·02CLI reference

deeprelay setup claude-code

Point Claude Code at deeprelay (settings.json env + apiKeyHelper)

Synopsis

Points Claude Code at deeprelay. After it runs, claude sends its requests to deeprelay's Anthropic-compatible /v1/messages endpoint and uses deeprelay models for every model slot.

What it writes

Setup merges these keys into a Claude Code settings file and leaves everything else in the file alone:

Key	Value
`env.ANTHROPIC_BASE_URL`	the API base without the trailing `/v1` (Claude Code adds `/v1/messages` itself)
`env.ANTHROPIC_MODEL`	the main model (`--model`)
`env.ANTHROPIC_DEFAULT_OPUS_MODEL`	the model for the `opus` alias (`--opus-model`)
`env.ANTHROPIC_DEFAULT_SONNET_MODEL`	the model for the `sonnet` alias (`--sonnet-model`)
`env.ANTHROPIC_DEFAULT_HAIKU_MODEL`	the model for the `haiku` alias (`--haiku-model`)
`env.ANTHROPIC_DEFAULT_FABLE_MODEL`	the model for the `fable` alias (`--fable-model`)
`env.ANTHROPIC_SMALL_FAST_MODEL`	the background-task model (same as `--haiku-model`)
`apiKeyHelper`	the absolute path of this `deeprelay` binary followed by `auth token`

Setup also removes env.ANTHROPIC_AUTH_TOKEN and env.ANTHROPIC_API_KEY from the file if they are there, and turns off a cloud-provider mode (CLAUDE_CODE_USE_BEDROCK, _VERTEX or _FOUNDRY) that is switched on. Claude Code uses any of these in preference to apiKeyHelper, so a key left over from another gateway would be sent to deeprelay instead of yours. The diff shows each removal with its value hidden, and --remove puts the old values back.

Every alias Claude Code can pick gets a deeprelay model, so a configured session never asks for a Claude model. CLAUDE_CODE_SUBAGENT_MODEL is not set, so subagents keep their own opus / sonnet / haiku choices, which resolve through the slots above.

Your key never lands in a file. apiKeyHelper makes Claude Code run deeprelay auth token whenever it needs the key, so the key stays in the deeprelay credentials file. The binary is referenced by its absolute path, resolved when you run setup, instead of by PATH lookup. If you move or reinstall deeprelay somewhere else, run setup again. Run setup from an installed binary, not go run.

Scopes and modes

Default (--scope user): writes ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json). Every project on this machine uses deeprelay.
--scope project: writes .claude/settings.local.json in the current directory, so only this project uses deeprelay. Setup asks git whether the file is ignored and warns if it is not.
--print: writes nothing. It prints export lines (including ANTHROPIC_AUTH_TOKEN with your key in plaintext) for you to paste into a shell. This is the only mode that shows the key.
--remove: undoes a previous setup for the chosen scope (see below).

Before anything is written

Setup runs the apiKeyHelper command once, exactly as Claude Code will, and uses the key it prints to check every chosen model. Each model must exist on deeprelay and support tool calling. Setup then makes a free /v1/messages/count_tokens call for each model. If any check fails, nothing is written and the command exits non-zero.

Setup then shows the settings file path, a key-by-key diff, and the undo command, and asks you to confirm. --yes skips the prompt for scripts. If stdin is not a terminal and --yes is missing, setup stops without writing.

These warnings always print to stderr, even with --yes:

the settings file already points ANTHROPIC_BASE_URL at a different endpoint, so replacing it redirects all Claude Code usage to deeprelay;
the settings file holds a credential or cloud-provider setting that outranks apiKeyHelper, which setup removes (see above);
with --scope project, your user settings file holds such a setting; setup does not edit that file, and Claude Code will not reach deeprelay until you remove it there;
ANTHROPIC_* variables are set in your shell, and a shell variable overrides the settings file (only the names are shown);
DEEPRELAY_API_KEY is set in your shell, so setup's check used that key; deeprelay auth token falls back to the saved credentials file wherever it is not set (for example when Claude Code starts from an IDE), so that file needs a working key too;
Claude Code is logged in to a Claude subscription and you chose user scope, so every project's usage routes to deeprelay instead of the subscription (consider --scope project).

Backups and undo

Setup keeps its files in the deeprelay config directory (~/.config/deeprelay, or $XDG_CONFIG_HOME/deeprelay). Before each write, it copies the current settings file into that directory's backups/claude-code folder. Each backup gets a timestamped name, and a later run never overwrites an earlier one. Setup also records which keys it added, changed or removed, and their earlier values, in the directory's setup folder (mode 0600). Your deeprelay key is never in it; a credential setup removed from the settings file is, so that --remove can restore it.

deeprelay setup claude-code --remove (add --scope project for a project setup) replays that record key by key:

keys setup added are deleted;
keys setup changed get their earlier values back;
keys setup removed (a conflicting credential) are put back;
keys you edited yourself after setup are left alone, with a warning naming each one.

--remove shows a diff and asks for confirmation like setup does. Running it again, or running it when setup never ran, reports "nothing to remove" and exits 0.

Default models

The defaults are models tested with Claude Code and chosen for reliable tool calling. Override any slot with its flag. Any model you pick must support tool calling.

Slot	Default	Why
Main, Opus, Sonnet and Fable (`--model`, `--opus-model`, `--sonnet-model`, `--fable-model`)	`deeprelay/deepseek-v4-pro`	The strongest tested model with thinking and reliable tool calls
Haiku and small-fast (`--haiku-model`)	`deeprelay/deepseek-v4.1-flash`	Covered by the flat plan, the same family as the main model, and it can see images; used for background tasks such as titles and summaries

deeprelay/glm-5.3 also completed a full Claude Code coding session with thinking and tool calls, and works as a main model. deeprelay/gpt-oss-120b completed one too and is a cheaper pay-as-you-go choice for --haiku-model if you are not on the flat plan.

Limitations

Claude Code's built-in WebSearch tool depends on an Anthropic server tool that deeprelay does not run, so it returns an error. Add a search MCP server to Claude Code instead. WebFetch runs locally as a client tool and is not affected.

Examples

# Configure Claude Code for every project (asks before writing)
deeprelay setup claude-code

# Only this project, no prompt
deeprelay setup claude-code --scope project --yes

# Pick a different main model
deeprelay setup claude-code --model deeprelay/glm-5.3

# Print shell exports instead of writing a file (shows your key)
deeprelay setup claude-code --print

# Undo
deeprelay setup claude-code --remove

deeprelay setup claude-code [flags]

Options

      --fable-model string    Model for the fable alias (default "deeprelay/deepseek-v4-pro")
      --haiku-model string    Model for the haiku alias and background tasks (default "deeprelay/deepseek-v4.1-flash")
  -h, --help                  help for claude-code
      --model string          Main model (ANTHROPIC_MODEL) (default "deeprelay/deepseek-v4-pro")
      --opus-model string     Model for the opus alias (default "deeprelay/deepseek-v4-pro")
      --print                 Print shell exports instead of writing any file (shows your key in plaintext)
      --remove                Undo a previous setup key by key
      --scope string          Where to write: user (~/.claude/settings.json) or project (.claude/settings.local.json) (default "user")
      --sonnet-model string   Model for the sonnet alias (default "deeprelay/deepseek-v4-pro")
      --yes                   Apply without the confirmation prompt (warnings still print)

Options inherited from parent commands

      --api-base string   API base URL (override with DEEPRELAY_API_BASE env) (default "https://api.deeprelay.ai/v1")
      --debug             Enable debug logging to stderr
      --no-preflight      Skip the plan/credit check before inference requests (override with DEEPRELAY_NO_PREFLIGHT env)
  -o, --output string     Output format: table|json (default table on TTY, json otherwise) (default "table")