CH·02CLI reference

deeprelay setup opencode

Point OpenCode at deeprelay

Synopsis

Points OpenCode at deeprelay. After it runs, opencode sends its requests to deeprelay's OpenAI-compatible /v1/chat/completions endpoint and starts on a deeprelay model.

What it writes

Setup edits OpenCode's global config: ~/.config/opencode/opencode.json (under $XDG_CONFIG_HOME when that is set), or the file $OPENCODE_CONFIG names. If only opencode.jsonc exists in that directory, setup edits that file. It changes two keys and leaves the rest of the file alone. Comments, trailing commas, formatting and every other provider stay exactly as they were.

The deeprelay provider:

{
  "provider": {
    "deeprelay": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "deeprelay",
      "options": {
        "baseURL": "https://api.deeprelay.ai/v1",
        "apiKey": "{env:DEEPRELAY_API_KEY}"
      },
      "models": {
        "deeprelay/deepseek-v4.1-flash": {
          "name": "deeprelay/deepseek-v4.1-flash",
          "limit": { "context": 131072, "output": 8192 }
        }
      }
    }
  },
  "model": "deeprelay/deeprelay/deepseek-v4.1-flash"
}

models holds every model in deeprelay's list of models tested with coding agents. The keys are exact deeprelay model IDs, because OpenCode sends them unchanged. limit.context and limit.output come from the deeprelay catalog. Setup leaves output out when the catalog does not list a maximum output.

model makes deeprelay OpenCode's default. OpenCode reads it as / and splits at the first slash, so the value is deeprelay/ followed by the full model ID.

baseURL is the API base setup runs against (--api-base, or DEEPRELAY_API_BASE), always ending in /v1.

Your key never lands in a file

apiKey holds {env:DEEPRELAY_API_KEY}. That is OpenCode's syntax for reading an environment variable when it starts. It is the name of a variable, not the key.

To set the variable, add this line to your shell rc (~/.zshrc, ~/.bashrc). Setup and --print print it with the absolute path of your deeprelay binary:

export DEEPRELAY_API_KEY="$('/usr/local/bin/deeprelay' auth token)"

Each new shell runs deeprelay auth token, which reads your key from the deeprelay credentials file (deeprelay login). The key is never stored in your rc file, opencode.json, the setup record or a backup. If you rotate the key, the next shell picks up the new one. If DEEPRELAY_API_KEY is not set when you run setup, setup warns and prints this line.

OpenCode started from a desktop launcher may not read your shell rc, so it will not see DEEPRELAY_API_KEY. Start it from a terminal, or set the variable for your desktop session.

Modes

Default: writes the deeprelay provider and the default model. Asks before writing.
--model : writes only that model instead of the curated list. It must exist on deeprelay and support tool calling.
--print: writes nothing. It prints the config snippet and the export line, so you can merge them into the file yourself.
--refresh: rewrites the models map, baseURL and the default model from the current list. It needs an earlier setup, and it shows a diff and backs up the file like setup does.
--remove: undoes a previous setup (see below).
--force: with --yes, replaces setup's entries even if you edited them (see below).

Project-level opencode.json files are not written. If the directory you run setup in has one, setup warns that it overlays the global file.

Before anything is written

Setup resolves your key the way deeprelay auth token does: from DEEPRELAY_API_KEY if it is set, or else from the credentials file. It reads the model list from GET /v1/models and checks that each model exists and supports tool calling. It makes no billed call. If the API does not serve a recommended list, setup uses the list built into the CLI and says so.

Setup then shows 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 you did not pass --yes, setup stops without writing. If nothing would change, setup says OpenCode is already configured.

Setup owns provider.deeprelay as a whole. If you edited it after setup (added a model or changed baseURL, say), a run asks before replacing your edit. --yes alone leaves the edited entry alone, writes everything else, and exits non-zero. --yes --force replaces it.

If the file is not valid JSON or JSONC, setup stops with an error and writes nothing.

Backups and undo

Before each write, setup copies the existing file into backups/opencode/ in the deeprelay config directory (the one holding your credentials file). A later run never overwrites an earlier backup. Setup also records which keys it added or changed, and their earlier values, in the setup directory next to it. No key is ever in either.

deeprelay setup opencode --remove replays that record:

provider.deeprelay is deleted if it still holds what setup wrote;
model gets its earlier value back, or is deleted if setup added it;
entries you edited after setup are left alone, with a warning.

Running --remove again, or when setup never ran, reports "nothing to remove" and exits 0. After removing, you can delete the DEEPRELAY_API_KEY line from your shell rc.

Default model

The default model is the first one in deeprelay's list of models tested with coding agents. A model covered by your plan comes first. Every other model on the list is in the models map, so /models in OpenCode can switch to it. Pick a single model with --model.

Examples

# Configure OpenCode (asks before writing)
deeprelay setup opencode

# No prompt
deeprelay setup opencode --yes

# Only one model
deeprelay setup opencode --model deeprelay/deepseek-v4-pro

# Print the snippet and the shell rc line
deeprelay setup opencode --print

# Update the model list from the catalog
deeprelay setup opencode --refresh

# Replace setup's entries even though you edited them
deeprelay setup opencode --refresh --yes --force

# Undo
deeprelay setup opencode --remove

deeprelay setup opencode [flags]

Options

      --force          With --yes, replace a setup-owned entry you have edited since the last run
  -h, --help           help for opencode
      --model string   Use this model instead of the curated list
      --print          Print the config snippet and export line instead of writing any file
      --refresh        Re-sync the configured models from the curated list
      --remove         Undo a previous setup entry by entry
      --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")