slug: introduction

Introduction

Open Agent Router (OAR) is a local AI Agent routing manager. It unifies API keys, model pools and routing strategies so every major agent — Claude Code, Codex, Hermes, OpenClaw, Gemini CLI and any OpenAI SDK client — can share a single local port (127.0.0.1:26969 by default).

One port, one config

Configure the base_url once. Switch groups or models from the UI or CLI later, without ever touching the agent's config file again.

Two modes, one backend

OAR ships in two modes that talk to the same backend:

Desktop mode — a Tauri desktop app for macOS, Linux and Windows. Bundles its own oar binary, runs as a system-tray app, supports auto-start (via launchd on macOS) and auto-update via the R2 CDN. Closing the window hides to tray — the backend service keeps running.
CLI mode — install the standalone oar binary via a one-liner script and manage the backend with oar start | stop | restart | status. Ideal for headless servers, Linux boxes without a GUI, and automation.

Both modes expose the same admin Web UI, admin API and agent proxy on :26969. Configuration made in one mode is visible in the other — they share a single SQLite store under ~/.open-agent-router/.

	Desktop mode	CLI mode
Install	Download installer	One-liner script
Start backend	Launch the app	`oar start`
Manage backend	Tray menu / window	`oar status`, `oar stop`, `oar restart`
Auto-start	launchd / autostart entry	manual or systemd unit
Auto-update	R2 CDN channel	`oar update`
Web UI	Built-in window	`http://127.0.0.1:26969`
Best for	Workstations	Headless / servers / CI

The problem it solves

Desktop AI developers typically juggle:

3+ API Keys — OpenCode Go, Anthropic, OpenAI, MiniMax and more.
Multiple agents running in parallel — Claude Code, Codex, Hermes.
Manual switching — every agent holds a different key, endpoints get copy-pasted back and forth.
Same model, different pools per project — you want one project on a cheap pool and another on a premium one.
Failover — when a model rate-limits, you want an automatic fallback within the same group.

OAR concentrates all of this into a single local service that every agent points at.

What it does

Protocol auto-adapt — agents speak Anthropic Messages, Codex Responses, OpenAI Chat or Google AI. OAR detects the inbound protocol and either passes through or converts.
Keypool management — multiple keys per platform instance, weighted rotation, rate-limit cooldown and automatic failover on 429.
Four routing methods — project, agent, group and model routes. Configure once and the base_url never changes.
Model mapping — alias tables map the model name an agent sends to the upstream real name.

Architecture

┌─ Desktop app (Tauri shell) ─────────────────────────┐
│  Window + system tray                               │
│        │ launch                                     │
│        ▼                                            │
│  oar init --from-app                                │
│  syncs bundled resources → ~/.open-agent-router/    │
│        │                                            │
│        ▼                                            │
│  Spawns / connects to backend service               │
│  (same oar binary, long-lived process)              │
└──────────────────────────────────────────────────────┘

┌─ CLI mode ───────────────────────────────────────────┐
│  oar start   →  runs the oar binary as a daemon      │
│  oar status  →  forwards to admin API                │
│  oar account list / oar group create …               │
│  (API forwarders to the running service)             │
└──────────────────────────────────────────────────────┘

             │  both modes hit the same backend
             ▼
┌─ Backend service (single process, single port) ─────┐
│                                                      │
│  Web UI    (browser, http://127.0.0.1:26969)         │
│  Admin API (/api/*)                                  │
│  Agent proxy                                         │
│  ├─ /project/:name/v1/*   → project route            │
│  ├─ /agent/:name/v1/*     → agent route              │
│  ├─ /group/:name/v1/*     → group direct             │
│  └─ /model/:name/v1/*     → model direct             │
│                                                      │
│  Express backend                                     │
│  ├─ Protocol adapters (pass-through or convert)      │
│  ├─ Keypool manager (rate-limit switch, rotation)    │
│  ├─ In-memory cache (full load on boot, dual-write)  │
│  └─ SQLite (node:sqlite, zero-dependency)            │
└──────────────────────────────────────────────────────┘

The oar binary is the backend service. In desktop mode the Tauri shell bundles it and spawns it on launch; in CLI mode oar start runs it directly. Admin-style CLI commands (oar account list, oar group create, oar status, …) are thin HTTP forwarders to the running service's admin API — they do not start a second backend.

Continue to the Quickstart to install OAR in the mode that suits you and configure your first route.

Quickstart