slug: routing

Routing Methods

OAR exposes four routing methods on a single local port (:26969 by default). The same port serves the admin API (/api/*) and the agent proxy. All four routing methods share the same pipeline — protocol detection, model selection, key pool — they only differ in how the route name is resolved.

Top-level reserved paths

/api/*        → admin API (platforms, models, groups, agents, projects CRUD)
/project/*    → project route
/agent/*      → agent route
/group/*      → group direct
/model/*      → model direct

These top-level segments are reserved and cannot be used as a project, agent, group or model name.

1. Project route (recommended)

A project binds an agent + group. Configure once and the base_url never changes — switching groups or models happens in the Web UI or CLI, never in the agent's config file.

http://127.0.0.1:26969/project/gz-project/v1/chat/completions
                         ^^^^^^^^^^^
                         project name

2. Agent route

Routes by agent name to that agent's default group.

http://127.0.0.1:26969/agent/claude/v1/messages
                         ^^^^^^
                         agent name

3. Group direct

Bypasses agent and project — speak directly to a named group.

http://127.0.0.1:26969/group/coding/v1/chat/completions
                         ^^^^^^
                         group name

4. Model direct

Bypasses the group — speak directly to a named model.

http://127.0.0.1:26969/model/GLM-5.2/v1/chat/completions
                         ^^^^^^^^
                         model name

When to use which

Project routes are recommended for production. The base_url carries only the project name, so group and model can be swapped without touching the agent. Use agent / group / model routes for ad-hoc testing or scripts.

Routing flow

Taking a project route as an example:

POST /project/gz-project/v1/chat/completions
  body: { model: "claude-sonnet-4" }

1. Extract project = gz-project from the path
2. Memory cache: gz-project → Claude Code → default group "coding"
3. Identify protocol from path: /v1/chat/completions = OpenAI
4. Memory cache: coding group → available model list
5. Body model = claude-sonnet-4 → match a model in the group
6. Model mapping → upstream real name
7. Check protocol consistency
   - match       → pass-through forward (zero overhead)
   - mismatch    → protocol adapter converts
8. Key pool picks a key by weight, forwards upstream
9. On failure, auto-switch to the next key

In-memory cache

On startup OAR loads every project, group, model and key into memory. The proxy path performs zero SQLite I/O during forwarding.

When the Web UI or CLI changes config, it writes to SQLite and updates the in-memory cache — the next request sees the change immediately.

Switching groups or models

Without changing the base_url, you can switch via three channels:

Web UI — open the project/agent, pick a different group — the next request reflects it instantly.
CLI — oar agent set-group <slug> --group-id <id> updates the agent's default group; oar project add-agent <name|id> --slug <slug> [--group-id <id>] rebinds a project. See CLI Reference.
Agent skill — detect a model failure and invoke the same CLI commands to auto-switch to a cheaper group.

Project vs global

Operation	What changes	Touch base_url?
First-time config	writes agent config file	once, then never
Switch agent default group	memory cache + SQLite	no
Switch project group	memory cache + SQLite	no
Switch project model	memory cache + SQLite	no
Daily routing	nothing on disk, in-memory routing	no

Continue to Protocol Adapters to see how OAR handles agents and upstreams that speak different protocols.

Core Concepts

Protocol Adapters