CodeRoute

CodeRoute Quick Start User Guide

This guide is for using the live CodeRoute service with an OpenAI-compatible coding agent.

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 '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:

AliasBest for
coding-autoDefault. Lets CodeRoute pick the right route.
coding-localLocal-only work. Avoids cloud fallback.
coding-balancedStronger local route for refactors and debugging.
coding-strongFrontier local route: GLM-5.2 Q3_K_M on the Mac Studio.
coding-glm-openrouterHosted GLM-5.2 through OpenRouter for faster/full-model testing.
coding-reviewCode review, security review, and risk-heavy checks.

Start with coding-auto. Use coding-strong when you explicitly want the local frontier model, or coding-glm-openrouter when you want hosted GLM-5.2.

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

4. Configure A Coding Agent

Any agent that supports an OpenAI-compatible API can use CodeRoute.

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-local": {
          "name": "CodeRoute Local"
        },
        "coding-balanced": {
          "name": "CodeRoute Balanced"
        },
        "coding-strong": {
          "name": "CodeRoute Strong"
        },
        "coding-glm-openrouter": {
          "name": "CodeRoute GLM 5.2 Hosted"
        },
        "coding-review": {
          "name": "CodeRoute Review"
        }
      }
    }
  }
}

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 Strong for the local GLM-5.2 Q3_K_M frontier route, or CodeRoute GLM 5.2 Hosted for OpenRouter-hosted GLM-5.2.

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."

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"
        }
      }
    }
  }
}

With that variant, start OpenCode with:


export CODEROUTE_API_KEY=<CODEROUTE_API_KEY>
opencode

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

5. Use CodeRoute With A Project

Production mounts project roots into the CodeRoute container:

Host pathCodeRoute path
/home/steve/projects/projects/home
/home/steve/hermes-workspaces/projects/hermes
/opt/projects/projects/opt

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.

6. 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.

7. 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.

8. Troubleshooting