CodeRouter

A desktop application that acts as a local OpenAI-compatible proxy router. Sits between AI coding tools (like OpenCode) and multiple upstream LLM providers, providing intelligent failover, cost management, model grouping, and seamless OpenCode configuration integration.

Built with Tauri 2.x (Rust sidecar + React/TypeScript frontend). The protected release workflow targets Linux AppImage, macOS DMG, and Windows NSIS/MSI packages; the asset list on each GitHub Release is the authority for what is currently downloadable.

If you use multiple LLM providers or multiple accounts with the same provider, CodeRouter lets you:

• Pool them together behind a single local endpoint — your AI tools only need to know about one URL
• Set up automatic failover — when one provider hits a rate limit or goes down, requests seamlessly fall over to the next provider in line
• Track estimated costs and usage - review locally observed provider usage, known cost estimates, daily quotas, and exportable reports
• Auto-configure OpenCode — one-click setup to route OpenCode agents through CodeRouter with per-agent model mapping

• Multi-Provider Aggregation — Add unlimited OpenAI-compatible and Anthropic-compatible providers behind a single local endpoint (localhost:4141)
• Model Discovery — Fetch available models and provider metadata, then fill missing OpenAI-compatible context/output limits from the community-maintained models.dev catalog
• ChatGPT Codex Discovery — Discover account-entitled Codex models via ChatGPT auth instead of stale preset model lists
• Per-Model Overrides — Manually correct context sizes, pricing, or model names when provider APIs return incomplete data
• Secure Credential Storage — API keys use the OS credential store by default; an owner-only plaintext credentials.json fallback exists only after explicit environment-variable opt-in

• Priority-Based Routing — Group multiple provider+model pairs under a single virtual model name with configurable priority ordering
• Automatic Failover — Transparent failover on HTTP 429 rate limits, policy or safety refusals, other HTTP 4xx client errors, daily quota exhaustion, consecutive errors, or latency timeouts — all configurable per group
• Smart Recovery — Exponential backoff with probe-based re-enable for rate-limited providers; quota-aware scheduling for daily resets
• Cooldown Tracking — See exactly why each provider entry is in cooldown with human-readable reasons
• Mixture of Agents - Fan out to reference groups and aggregate their output under explicit data-sharing, provider, residency, tool-result, and redaction controls. See docs/security.md and docs/compatibility.md for the privacy and accounting boundaries.

• SQLite-Backed Metrics — Per-provider costs, token usage, latency percentiles, and request logs
• Live Dashboard — Real-time token throughput, provider health cards, and recent request feed
• Historical Charts — Cost and token usage by provider, request volume by group, with date range filtering
• CSV Export — Download your usage data for analysis

• One-Click Setup — Auto-configure OpenCode to use CodeRouter as a provider
• Agent Mapping — Assign different model groups to OpenCode agents (build, plan, general, explore)
• Custom Agents & Subagents — Create specialized agents from templates or scratch, saved as markdown files in OpenCode's native format. Includes AI-powered prompt enhancement, permission management, and model group assignment
• Surgical JSON Patching — Only updates the relevant sections of OpenCode config, preserving all other settings

• System Tray — Green/red status indicator, quick start/stop proxy, hide-to-tray on window close
• Dark Theme UI — Built with shadcn/ui + Tailwind CSS
• Verified Packaging Contract — CI builds every advertised package on native runners, signs each Tauri updater payload, and verifies package structure, architecture, startup, checksums, and provenance; macOS and Windows native packages are currently distributed without platform code signing

• Linux x86_64 packages use an Ubuntu 22.04/glibc 2.35 build and smoke-test baseline; older distributions are not guaranteed
• The intended protected matrix also covers macOS x86_64/aarch64 and Windows x86_64; check the selected release for actual availability
• Linux development builds require GTK3/WebKit2GTK 4.1, AppIndicator, OpenSSL/pkg-config, librsvg2-dev, and patchelf
• Linux package launch verification additionally uses Xvfb; release TUI verification uses a pseudo-terminal
• Node and Rust versions are pinned by .node-version and rust-toolchain.toml

Grab an artifact that is actually listed on the selected Release. Historical and future release matrices differ.

chmod +x <DOWNLOADED_APPIMAGE>
./<DOWNLOADED_APPIMAGE>

On Linux, first launch normally creates ${XDG_CONFIG_HOME:-~/.config}/coderouter/ and ${XDG_DATA_HOME:-~/.local/share}/coderouter/. macOS and Windows use their platform directories; see docs/data-locations.md.

# Install system dependencies (Debian/Ubuntu)
sudo apt-get update
sudo apt-get install -y build-essential curl file libgtk-3-dev \
  libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev \
  libssl-dev patchelf pkg-config

# Clone and build
git clone https://github.com/CWinthorpe/codeRouter.git
cd codeRouter
npm ci

# Development mode
make dev

# Production build (AppImage)
make build

The AppImage will be produced under target/release/bundle/appimage/.

The sidecar exposes OpenAI-compatible chat endpoints on http://localhost:4141 by default:

Management endpoints, including /health, are served on the management port (http://localhost:4142 by default). Remote public proxy bindings require the configured CodeRouter bearer token. See docs/compatibility.md for the full endpoint, protocol, field, and response-header compatibility matrix.

Non-loopback public bindings also require configured TLS certificate-chain/private-key paths; remote clients use HTTPS and must trust the issuing CA. Management remains loopback-only. See docs/security.md for the trust and rotation contract.

# Check health
curl http://localhost:4142/health

# List available model groups
curl http://localhost:4141/v1/models

# Chat completion (non-streaming)
curl http://localhost:4141/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "glm-5-router", "messages": [{"role": "user", "content": "Hello"}]}'

# Chat completion (streaming)
curl http://localhost:4141/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "glm-5-router", "messages": [{"role": "user", "content": "Hello"}], "stream": true}'

Add CodeRouter as a provider in your OpenCode config:

{
  "provider": {
    "coderouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CodeRouter",
      "options": {
        "baseURL": "http://localhost:4141/v1",
        "apiKey": "coderouter"
      }
    }
  }
}

Or use the OpenCode Setup tab in the CodeRouter UI for automatic configuration with agent mapping.

On Linux with default XDG settings, files are laid out as follows:

~/.config/coderouter/
  config.json          # App settings (port, host, refresh interval, log verbosity)
  providers.json       # Upstream provider configs
  groups.json          # Model group definitions
  proxy.token          # Secret bearer token for authenticated public-proxy access
  credential-keys.json # Credential cleanup identifiers, not credential values

~/.local/share/coderouter/
  metrics.db           # SQLite usage/metrics database
  proxy.log            # Sidecar log file

API keys use the OS credential store by default. If secure storage is unavailable, CodeRouter fails closed unless CODEROUTER_ALLOW_PLAINTEXT_CREDENTIAL_FALLBACK=1 is set; that opt-in writes unencrypted values to credentials.json in the config directory. See docs/security.md and docs/data-locations.md.

CodeRouter includes a terminal UI for managing providers, groups, usage, and settings from the command line. Built with Ratatui.

# Build TUI binary only
make tui

# Or via build.sh
./build.sh --tui-only

# Build both GUI (AppImage) and TUI
./build.sh --tui

# Dev mode (with debug output)
make tui-dev

# Or run the release binary directly
./target/release/coderouter-tui

# Install the target
rustup target add aarch64-unknown-linux-gnu

# Build for ARM64
make tui-arm64

# Note: Linux ARM64 TUI builds are local/development artifacts until added to release/artifacts.json.

Page-specific keys are shown in the help overlay (press ?).

Official publication is a manually dispatched GitHub Actions release workflow. Do not create the tag first. Only stable MAJOR.MINOR.PATCH versions are accepted. After a new version is reviewed and merged to green main, run:

git switch main
git pull --ff-only
./release.sh

release.sh only dispatches the workflow, binding it to the full GitHub main commit SHA. The same reusable CI gates must pass for that exact commit before jobs can enter the release environment. Publication atomically creates a new lightweight tag at that SHA, rejects reused versions, verifies native GUI/TUI startup plus package structure and architecture, cryptographically checks updater signatures, generates a Syft SPDX SBOM and GitHub provenance attestations, then byte-verifies an exact draft asset set immediately before publishing.

The updater archives and installer updater payloads are signed with CodeRouter's Tauri updater key. The macOS DMGs/apps and Windows executables are not currently Apple-notarized or Authenticode-signed, so those operating systems may display an unidentified-developer warning during manual installation.

For local development-only Linux packages:

./build.sh --release   # unsigned; cannot publish or satisfy the official platform matrix
make release           # dispatches the protected GitHub workflow; does not publish locally

The table below is the contract for the next successfully completed protected release, not a claim about historical releases.

Runnable artifacts also receive GitHub/Sigstore build-provenance attestations verifiable with gh attestation verify.

Linux / macOS:

tar xzf coderouter-tui-<VERSION>-<platform>.tar.gz
cd coderouter-tui-<VERSION>-<platform>
chmod +x coderouter-tui coderouter-proxy
./coderouter-tui

Windows:

Expand-Archive coderouter-tui-<VERSION>-windows-x86_64.zip
cd coderouter-tui-<VERSION>-windows-x86_64
.\coderouter-tui.exe

src-tauri/tauri.conf.json supplies the displayed release version. The release contract requires matching versions in package.json, package-lock.json, the three Cargo manifests, and corresponding Cargo.lock package records. See docs/release.md; no release tag is pushed manually.

make release-notes

# Run Rust workspace tests
make test          # cargo test --workspace --locked

# TypeScript check
npx tsc --noEmit

# Frontend tests and release-contract fixtures
npm test
make release-contract

# Regenerate/check locked Cargo and production npm notices
npm run licenses:generate
npm run licenses:check

# Build AppImage
make build         # runs ./build.sh

# Build TUI only
make tui           # cargo build --release --locked -p coderouter-tui

# Run TUI in dev mode
make tui-dev       # cargo run -p coderouter-tui

# Stage the GUI sidecar for a fresh clone
npm run stage:sidecar

# Dev mode with hot reload
make dev           # npm run tauri dev

codeRouter/
├── sidecar/              # Rust proxy binary
│   └── src/
│       ├── config/       # JSON config store + serde models
│       ├── credentials/  # libsecret keychain wrapper
│       ├── metrics/      # SQLite recorder, queries, scheduler
│       ├── models/       # Upstream model discovery
│       ├── opencode/     # OpenCode config writer + custom agents
│       └── proxy/        # Axum server, router, protocol translator
├── src-tauri/            # Tauri desktop shell
│   └── src/
│       ├── commands.rs   # All Tauri IPC commands
│       └── main.rs       # Entry point, sidecar lifecycle, tray
├── src/                  # React frontend
│   ├── components/       # AppShell, CustomAgentsManager, shared UI
│   ├── pages/            # Dashboard, Providers, Groups, etc.
│   ├── store/            # Zustand global state
│   ├── lib/ipc.ts        # Typed IPC wrapper
│   └── types/index.ts    # Shared TypeScript types
├── build.sh              # AppImage build script
├── Makefile              # build / dev / test / tui targets
└── tui/                  # Terminal UI (Ratatui)
    └── src/
        ├── main.rs       # Entry point, panic hook, sidecar lifecycle
        ├── app.rs        # App state, key routing, tab management
        ├── pages/        # Dashboard, Providers, Groups, OpenCode, Usage, Settings
        ├── widgets/      # Tab bar, status bar, help overlay, toast
        └── presets.rs    # Provider preset definitions

MIT