User Guide

Quick start

One command to install. Replace sk-paste-your-key-here with the key the operator sent you.

curl -fsSL https://guide.9relay.com/install.sh | bash -s -- sk-paste-your-key-here

This installs in wrapper mode: your default claude and codex commands are unchanged (they still talk to api.anthropic.com / OpenAI like before, useful if you have your own subscription). The install drops dedicated commands on your PATH — claude-9relay, claude-9relay-1m, and codex-9relay — that route through 9relay instead. It also adds a 9relay provider to OpenCode's config if you use that (see the OpenCode section).

Run them directly, no source step needed:

claude                              # your own subscription (unchanged)
claude-9relay                       # through 9relay (Opus, 200K context)
claude-9relay-1m                    # through 9relay (Opus, 1M context -- ~2x cost above 200K)
claude-9relay --model coding-cheap  # through 9relay with a specific alias

codex                               # your own OpenAI account (unchanged)
codex-9relay                        # through 9relay

curl -fsSL https://guide.9relay.com/install.sh | bash -s -- sk-... --mode global

Want to inspect the script first? Read it before piping:

curl -fsSL https://guide.9relay.com/install.sh   # read
curl -fsSL https://guide.9relay.com/install.sh | bash -s -- sk-...   # then run

powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((irm https://guide.9relay.com/install.ps1))) -Key sk-paste-your-key-here"

Set up Claude Code

For permanent setup, add the two export lines to your shell config so they survive new terminal windows.

1. Edit your shell config

If you use zsh (default on macOS), edit ~/.zshrc. If you use bash, edit ~/.bashrc.

export ANTHROPIC_BASE_URL="https://claude.9relay.com"
export ANTHROPIC_AUTH_TOKEN="sk-paste-your-key-here"

2. Reload the shell

source ~/.zshrc     # or ~/.bashrc

3. Launch

claude --model coding-claude

You should see the Claude Code banner show coding-claude · API Usage Billing and a prompt. Try asking "say hi in three words" to verify the round trip works.

Set up Codex CLI

For Codex CLI, the relay is configured as a custom OpenAI-compatible provider.

1. Edit Codex config

Open or create ~/.codex/config.toml and add this block (don't overwrite anything that's already there):

model = "coding-codex"
model_provider = "9relay"

[model_providers.9relay]
name = "9relay"
base_url = "https://api.9relay.com/v1"
env_key = "OPENAI_API_KEY"

2. Set the API key

Add to ~/.zshrc or ~/.bashrc:

export OPENAI_API_KEY="sk-paste-your-key-here"

Then source the file.

3. Launch

codex

Your first session

If you've never used Claude Code or Codex before, here's a 10-minute warmup that builds intuition fast.

1. Open a project you know well. Don't start with an empty directory — give it real code to look at.
2. Ask it to explain something. "What does src/auth.ts do?" Read the answer critically — does it match reality? This calibrates your trust.
3. Ask for a tiny change. "Add a docstring to the verifyToken function in src/auth.ts." See how it proposes edits.
4. Ask for a small bug fix. If you have an open issue, paste it in. "Issue #42 says the date parser breaks on YYYY-MM. Find the cause and propose a fix."
5. Verify everything before accepting. Run tests, read the diff, check git status. The model is fast and confident — your job is to be the slow careful one.

Working effectively

Pick the right model for the job

Switch on the fly: inside Claude Code, type /model to pick. In Codex, pass --model on the command line.

Give it real context

The model can only reason about what it sees. Before asking a complex question, make sure the relevant files are in its context — paste them, mention them by path, or open them in your editor if Claude Code is attached.

Plan before doing

For anything non-trivial, ask the model to plan first, then implement. Two-step prompts work much better than one-step:

1. "Read src/payments/*.ts and describe the current
    flow when a card payment fails. Don't write code yet."

2. (after reading the plan)
   "Now implement the retry logic you described."

Verify, don't trust

Always run tests, lint, and build after the model makes changes. Always read the diff. The model is fast and confident — your job is to be the slow careful one.

Common tasks

Prompt patterns that work well. Copy, adapt, and use.

Add a feature

"I want to add a CSV export to the reports page.
The data source is src/reports/data.ts. Existing
export buttons live in src/components/ExportMenu.tsx.
Follow the same pattern. Add tests for the CSV
formatting in src/reports/__tests__/."

Refactor a file

"src/api/users.ts is 400 lines and mixes HTTP handling
with business logic. Split it: keep HTTP in users.ts,
move business logic to src/users/service.ts. Don't
change behavior. Add or update tests as needed."

Debug a failing test

"Test 'src/auth/__tests__/login.test.ts' is failing
on the third assertion. Read the test, read the
implementation, identify the root cause, and propose
a fix. Show your reasoning before patching."

Generate tests for existing code

"Write tests for src/utils/dateRange.ts covering:
- happy path
- empty input
- timezone edges
- invalid date strings
Match the style of existing tests in src/utils/__tests__/."

Code review

"Review the diff between main and feat/new-checkout.
Focus on: error handling, edge cases, security, and
whether tests cover the new behavior. Be concise and
prioritize CRITICAL > HIGH > MEDIUM."

Explain a codebase

"I just inherited this repo. Walk me through the
overall architecture: where requests come in, what
the data flow looks like, where state is stored,
and which 3 files I should read first."

Quota and billing

Your plan has a monthly budget (in USD), an RPM limit (requests per minute), and a TPM limit (tokens per minute). Hit any of them and the relay returns a clear error — it will not silently route you to a more expensive model.

Check your usage

The installer also sets up 9relay-usage — a small command that shows your own spend against your plan's budget, your model mix, and a forecast of where the month is heading. It reads the key the installer already saved, so there's nothing to configure.

9relay-usage  # this billing period: spend vs budget, model mix, forecast
9relay-usage --window 7d  # narrower window: 24h | 7d | 30d | all
9relay-usage --compact  # short summary
9relay-usage --oneline  # one line, fits a status bar
9relay-usage --json  # machine-readable

The forecast tells you whether you're on track, at risk, or over budget for the period, and the projected run-out date if you keep the current pace.

Inside Claude Code

The installer also adds a /9relay-usage slash command. Type it in any Claude Code session and Claude will run the tool and summarize your spend, model mix, and forecast in plain language. Asking naturally works too — "how much 9relay budget do I have left?"

irm https://api.9relay.com/usage -Headers @{ Authorization = "Bearer sk-paste-your-key-here" }

Numbers update within about 10 seconds of a request finishing, and your key only ever sees your own usage.

Troubleshooting

Privacy

9relay does not persist your prompts or model responses. Only metadata (token counts, latency, model alias, status code) is logged — never your source code or your conversations. Request headers including your API key are redacted from access logs.

If you observe behavior that suggests otherwise, message the operator immediately.

Use 9relay from Cursor

Cursor configures providers in its UI rather than via shell, so there's no install script for it. Two minutes in Settings:

1. Cursor → Settings → Models → OpenAI Compatible (or "Custom API")
2. Base URL: https://api.9relay.com/v1
3. API Key: your sk-... key
4. Add coding-opus, coding-opus-1m, coding-claude, coding-codex, coding-gemini, and coding-cheap as available models

From then on, Cursor's "Chat" and "Composer" features can use any of the public aliases. Your normal Cursor login still works for the editor itself — only model traffic routes through 9relay.

Use 9relay from OpenCode

If you ran the one-line installer, OpenCode is already configured — a 9relay provider was merged into ~/.config/opencode/opencode.json (your other providers and default model are untouched). Launch opencode and pick a 9relay/... model via the /models command.

Setting it up by hand instead? Add this under provider in ~/.config/opencode/opencode.json:

"9relay": {
  "npm": "@ai-sdk/anthropic",
  "name": "9relay",
  "options": {
    "baseURL": "https://claude.9relay.com/v1",
    "apiKey": "sk-paste-your-key-here"
  },
  "models": {
    "coding-opus":   { "name": "Claude Opus (9relay)" },
    "coding-claude": { "name": "Claude Sonnet (9relay)" }
  }
}

Two details that matter: the baseURL must end in /v1 (OpenCode appends /messages itself — copying the Claude Code value without /v1 gives a 404), and model ids must be the 9relay aliases exactly. Prefer not to put the key in the file? "apiKey": "{file:/home/you/.9relay/key}" (absolute path) or "{env:NINERELAY_KEY}" work too — the installer uses exactly that.

Use 9relay from JetBrains (GoLand)

Works in GoLand, IntelliJ IDEA, PyCharm, WebStorm — same steps everywhere. The recommended path reuses the claude-9relay command you already have:

1. Run the one-line installer (if you haven't).
2. Settings → Plugins → Marketplace → install "Claude Code [Beta]" (vendor: Anthropic).
3. Settings → Tools → Claude Code [Beta] → set Claude command to the wrapper path: the output of command -v claude-9relay (Windows: %USERPROFILE%\.9relay\bin\claude-9relay.cmd).
4. Launch with ⌘+Esc (macOS) / Ctrl+Esc (Windows/Linux).

Installed with --mode global? Skip step 3 — plain claude is already routed, the plugin works out of the box.

Two alternatives that don't need Claude Code at all: JetBrains AI Assistant (add an "OpenAI API-compatible" provider with URL https://api.9relay.com/v1 + your key — note inline code completion stays on JetBrains' own models), and the Cline plugin (provider "Anthropic" → "Use custom base URL" → https://claude.9relay.com, no /v1). If the plugin's terminal says claude: command not found, re-run the installer (it sets up Claude Code from the China npm mirror), then re-check the Claude command path.

Switch back to your own subscription

In wrapper mode, plain claude (i.e. anything that isn't claude-9relay) already uses your own subscription — no uninstall needed if you only want to stop using the relay temporarily. To fully remove 9relay (deletes the claude-9relay, claude-9relay-1m, and codex-9relay shims, the stashed key at ~/.9relay/key, and any rc-file block):

curl -fsSL https://guide.9relay.com/uninstall.sh | bash

On native Windows (cmd or PowerShell):

powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((irm https://guide.9relay.com/uninstall.ps1)))"

The uninstaller only touches files it can identify as its own (shims are checked for a guide.9relay.com marker), and any rc-file edit leaves a .bak backup. The Windows version is value-guarded the same way — it never clears an env var you set yourself.

To clear the env vars in your current shell (only needed if you installed with --mode global):

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL OPENAI_API_KEY OPENAI_BASE_URL

For Cursor, just delete the 9relay model entry in Settings → Models. The uninstaller also removes the 9relay provider block from OpenCode's config (only that block — your other providers stay). For JetBrains, clear the Claude command setting if you pointed it at the wrapper.

Support

Phase 1 is invitation-only. There's no ticket system — just reply to the email or message you got the key in. That's a direct line to the operator.

For questions about Claude Code itself (commands, features, key bindings), see the official Claude Code docs. For Codex CLI, see the Codex repo.