CodeRoute Quick Start User Guide

This guide is for using the live CodeRoute service with an OpenAI-compatible coding agent. Most clients use /v1/chat/completions; current OpenAI Codex CLI uses CodeRoute's /v1/responses adapter through wire_api = "responses".

For client-specific setup across OpenCode, Codex CLI, Cline, Roo Code, Cursor, Aider, Continue, and Claude Code caveats, see the Harness Setup Guide.

1. Get Your API Settings

Production endpoint:

https://coderoute.ai/v1
      

Get the API key from pchomelab:

ssh pchomelab 'sudo docker exec coderoute-coderoute-api-1 printenv CODEROUTE_API_KEY'
      

Export the common OpenAI-compatible variables:

export OPENAI_BASE_URL=https://coderoute.ai/v1
export OPENAI_API_KEY=<CODEROUTE_API_KEY>
export OPENAI_MODEL=coding-auto
      

2. Choose A Model Alias

Use CodeRoute aliases, not provider model names:

Start with coding-auto. On pchomelab it prefers the dedicated 4090 Qwen workhorse first and uses hosted OpenRouter GLM-5.2 instead of the Mac Studio GLM route. Use coding-glm-local only when you explicitly want the slower Mac Studio Q3_K_M route, coding-ornith-local when you want the local Ornith agentic coding model, or coding-gpt55 when you explicitly want GPT-5.5.

Current Live Routing Snapshot

Validated on July 2, 2026 against https://coderoute.ai/v1:

The named *-free aliases route to their fixed OpenRouter :free models. They are useful for opportunistic testing, but current availability depends on OpenRouter's free provider pool and account limits.

Free OpenRouter Routes

CodeRoute can also route to named OpenRouter :free models. These are useful for development, smoke tests, and cost-sensitive work, but they are still external aggregator-cloud routes and OpenRouter applies free-model rate limits.

OpenRouter free variants are limited to 20 requests per minute. Daily limits are typically 50 free-model requests unless the OpenRouter account has purchased at least $10 in credits, which raises the free-model daily limit to 1000.

If a free route returns 502, check the response body and the dashboard provider-health panel. During July 2 validation, coding-qwen3-coder-free and coding-qwen-next-free both reached CodeRoute but failed upstream through OpenRouter free-provider limits. Switch to coding-auto, coding-local, coding-glm-openrouter, or coding-gpt55 for reliable work.

Adaptive aliases such as coding-auto, coding-balanced, coding-local, coding-strong, and coding-review retry the next allowed candidate after retryable provider failures such as network errors, 429, and 5xx. Fixed aliases such as coding-glm-openrouter, coding-glm-local, coding-ornith-local, coding-gpt55, and the named *-free routes do not silently switch providers because those aliases mean "use exactly this route."

3. Smoke Test

curl https://coderoute.ai/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "coding-auto",
    "messages": [
      {"role": "user", "content": "Reply with exactly: CodeRoute ready"}
    ],
    "max_tokens": 64,
    "temperature": 0
  }'
      

For a routing check, inspect these response headers:

x-coderoute-selected-model
x-coderoute-step-type
x-coderoute-codegraph-signal
x-coderoute-estimated-max-cost-usd
x-coderoute-actual-cost-usd
      

x-coderoute-estimated-max-cost-usd is a budget guardrail based on the requested output budget. It is not actual spend. When the provider returns usage accounting, CodeRoute records the provider-reported cost as actual spend.

4. Check Usage

Current usage ledger:

curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://coderoute.ai/v1/coderoute/usage
      

Recent sessions and request drill-down:

curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://coderoute.ai/v1/coderoute/sessions
      

Monthly workspace report:

curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  "https://coderoute.ai/v1/coderoute/reports/monthly?months=3&group_by=workspace"
      

Important cost fields:

For OpenRouter-hosted models, OpenRouter Activity remains the provider-side billing reference. CodeRoute uses returned usage accounting to keep its own request/session ledger aligned.

5. Send Budget Alert Webhooks

CodeRoute can send the same budget/anomaly alerts shown in the dashboard to an external webhook. Configure the API container with:

CODEROUTE_ALERT_WEBHOOK_URL=<https endpoint>
CODEROUTE_ALERT_WEBHOOK_BEARER_TOKEN=<optional receiver token>
CODEROUTE_ALERT_MIN_SEVERITY=warning
CODEROUTE_ALERT_TIMEOUT_SECONDS=5
      

Trigger a notification for the current alert window:

curl -X POST \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  "https://coderoute.ai/v1/coderoute/alerts/notify?min_severity=warning"
      

If the webhook URL is unset, the endpoint returns enabled: false and does not send anything. If no alerts match min_severity, it returns enabled: true and sent: false. Sent payloads include a deterministic notification_id, and CodeRoute also sends that value to the receiver as X-CodeRoute-Alert-Id so receivers can dedupe retries.

6. Configure A Coding Agent

Any agent that supports an OpenAI-compatible API can use CodeRoute. For Codex CLI, use the Codex-specific setup below so it speaks the Responses wire format. For Anthropic-compatible clients, use https://coderoute.ai/anthropic as the base URL so /v1/messages maps to CodeRoute's /anthropic/v1/messages adapter.

Generic provider config:

{
  "provider": "openai-compatible",
  "baseURL": "https://coderoute.ai/v1",
  "apiKey": "<CODEROUTE_API_KEY>",
  "model": "coding-auto"
}
      

For full harness-specific instructions, use:

https://coderoute.ai/harnesses
      

OpenCode Setup

OpenCode can use CodeRoute as a custom OpenAI-compatible provider.

1. Create or edit either your global config:

mkdir -p ~/.config/opencode
$EDITOR ~/.config/opencode/opencode.json
      

Or add a project-local opencode.json in the repo you are working on.

2. Add this provider block:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "coderoute/coding-auto",
  "provider": {
    "coderoute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CodeRoute",
      "options": {
        "baseURL": "https://coderoute.ai/v1"
      },
      "models": {
        "coding-auto": {
          "name": "CodeRoute Auto"
        },
        "coding-cheap": {
          "name": "CodeRoute Cheap"
        },
        "coding-local": {
          "name": "CodeRoute Local"
        },
        "coding-balanced": {
          "name": "CodeRoute Balanced"
        },
        "coding-strong": {
          "name": "CodeRoute Strong"
        },
        "coding-glm-openrouter": {
          "name": "CodeRoute GLM 5.2 Hosted"
        },
        "coding-glm-local": {
          "name": "CodeRoute GLM 5.2 Local"
        },
        "coding-ornith-local": {
          "name": "CodeRoute Ornith Local"
        },
        "coding-gpt55": {
          "name": "CodeRoute GPT-5.5"
        },
        "coding-review": {
          "name": "CodeRoute Review"
        },
        "coding-qwen3-coder-free": {
          "name": "CodeRoute Qwen3 Coder Free"
        },
        "coding-north-mini-code-free": {
          "name": "CodeRoute North Mini Code Free"
        },
        "coding-laguna-xs-free": {
          "name": "CodeRoute Laguna XS Free"
        },
        "coding-laguna-m-free": {
          "name": "CodeRoute Laguna M Free"
        },
        "coding-nemotron-super-free": {
          "name": "CodeRoute Nemotron Super Free"
        },
        "coding-gpt-oss-120b-free": {
          "name": "CodeRoute GPT OSS 120B Free"
        },
        "coding-qwen-next-free": {
          "name": "CodeRoute Qwen Next Free"
        },
        "coding-gemma-4-26b-free": {
          "name": "CodeRoute Gemma 4 26B Free"
        }
      }
    }
  }
}
      

3. Add the CodeRoute API key in OpenCode:

/connect
      

Select Other, use provider ID coderoute, and paste your CODEROUTE_API_KEY.

4. Restart OpenCode, then select a model:

/models
      

Choose CodeRoute Auto for normal work, CodeRoute GLM 5.2 Hosted for OpenRouter-hosted GLM-5.2, CodeRoute Ornith Local for the Mac Studio Ornith route, or CodeRoute GPT-5.5 for premium OpenAI work.

One-shot free Qwen3 Coder smoke test:

export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
opencode run --model coderoute/coding-qwen3-coder-free \
  "Do not edit files. Reply with the model route you are using."
      

One-shot hosted GLM-5.2 smoke test:

export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
opencode run --model coderoute/coding-glm-openrouter \
  "Do not edit files. Reply with the model route you are using."
      

One-shot Mac Studio GLM-5.2 Q3_K_M smoke test:

export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
opencode run --model coderoute/coding-glm-local \
  "Do not edit files. Reply with the model route you are using."
      

One-shot Mac Studio Ornith 1.0 35B smoke test:

export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
opencode run --model coderoute/coding-ornith-local \
  "Do not edit files. Reply with the model route you are using."
      

One-shot GPT-5.5 smoke test:

export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
opencode run --model coderoute/coding-gpt55 \
  "Do not edit files. Reply with the model route you are using."
      

Optional environment-key variant:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "coderoute/coding-auto",
  "provider": {
    "coderoute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CodeRoute",
      "options": {
        "baseURL": "https://coderoute.ai/v1",
        "apiKey": "{env:CODEROUTE_API_KEY}"
      },
      "models": {
        "coding-auto": {
          "name": "CodeRoute Auto"
        },
        "coding-strong": {
          "name": "CodeRoute Strong"
        },
        "coding-glm-openrouter": {
          "name": "CodeRoute GLM 5.2 Hosted"
        },
        "coding-glm-local": {
          "name": "CodeRoute GLM 5.2 Local"
        },
        "coding-ornith-local": {
          "name": "CodeRoute Ornith Local"
        },
        "coding-gpt55": {
          "name": "CodeRoute GPT-5.5"
        }
      }
    }
  }
}
      

With that variant, start OpenCode with:

export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
opencode
      

Codex CLI Setup

Add CodeRoute to your user-level Codex config, usually ~/.codex/config.toml:

model = "coding-auto"
model_provider = "coderoute"

[model_providers.coderoute]
name = "CodeRoute"
base_url = "https://coderoute.ai/v1"
env_key = "CODEROUTE_API_KEY"
wire_api = "responses"
      

Run a quick smoke test:

export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
codex exec --sandbox read-only \
  -m coding-glm-openrouter \
  "Do not edit files or run commands. Reply exactly: codex coderoute ok"
      

Start an interactive project session:

export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
codex -m coding-auto
      

Aider-style environment:

export AIDER_MODEL=openai/coding-auto
export AIDER_OPENAI_API_BASE=https://coderoute.ai/v1
export AIDER_OPENAI_API_KEY=<CODEROUTE_API_KEY>
      

For a one-off strong-model run:

export OPENAI_MODEL=coding-strong
      

7. Use CodeRoute With A Project

Production mounts project roots into the CodeRoute container:

If your project is /home/steve/projects/my-app on pchomelab, refer to it as:

/projects/home/my-app
      

When your agent supports request metadata, include project context:

{
  "repo_path": "/projects/home/my-app",
  "repo_name": "my-app",
  "changed_files": ["src/main.py", "tests/test_main.py"],
  "symbols": ["route_request"],
  "step_hint": "debugging",
  "session_id": "my-app-debug-001"
}
      

If your agent cannot send metadata, put the project path and task type in the prompt. CodeRoute still routes from the prompt itself.

8. Check CodeGraph Status

curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  "https://coderoute.ai/v1/coderoute/codegraph/status?repo_path=/projects/home/my-app"
      

CodeGraph signals are advisory. If CodeGraph is unavailable or the path is outside the allowed roots, CodeRoute falls back to normal prompt-based routing.

9. Send Execution Feedback

From this repo, you can wrap a command and post feedback:

CODEROUTE_API_BASE=https://coderoute.ai \
CODEROUTE_API_KEY=$OPENAI_API_KEY \
scripts/coderoute-helper.py run-feedback \
  --session-id my-app-debug-001 \
  -- pytest
      

Feedback helps CodeRoute escalate later requests in the same session after failures.

10. Troubleshooting

• 401 Unauthorized: refresh CODEROUTE_API_KEY from pchomelab.
• Cloudflare blocks a client: make sure your tool sends a normal user agent. curl and most coding agents are fine.
• CodeGraph signal is none: confirm repo_path is under /projects/home, /projects/hermes, /projects/opt, or /app.
• Mac Studio local GLM is unavailable: on the Mac Studio, run lms server start --bind 0.0.0.0 and lms load glm-5.2 --identifier glm-5.2, then retry coding-glm-local.
• Mac Studio local Ornith is unavailable: on the Mac Studio, run lms server start --bind 0.0.0.0 and lms load ornith-1.0-35b --identifier ornith-1.0-35b, then retry coding-ornith-local.
• Local GLM or Ornith gives an empty answer on tiny tests: use a larger output cap. These local reasoning models emit hidden reasoning first; use at least 256 for local GLM smoke tests and at least 768 for local Ornith smoke tests.
• Hosted GLM-5.2 testing: use coding-glm-openrouter.
• GPT-5.5 testing: use coding-gpt55. CodeRoute removes unsupported temperature values before forwarding to GPT-5.5.
• OpenCode budget_exceeded: lower the model output-token cap, usually limit.output or maxOutputTokens. Start with 4096 for hosted GLM-5.2 and 2048 for GPT-5.5.
• Free OpenRouter model returns 429: wait for the per-minute or daily free-model limit to reset, or use coding-auto, coding-local, or a paid hosted route.
• Model not found: use CodeRoute aliases like coding-auto, not provider names like glm-5.2-q3-k-m.