How routing works in Lyre

You start a coding task with one AI model. Halfway through, its account hits a limit. You have another account available, but switching means changing the tool's configuration and deciding where the next request should go.

Routing puts those choices in one place. A gateway receives a model request, looks at the model or route you selected, and forwards it to a connected provider. You control the available models, accounts and fallback rules.

In Lyre, this optional gateway is powered by OmniRoute. You can keep using your agents directly, or choose the gateway when you want to manage several model sources through one connection.

Routing, models and agents

A model produces the response. A provider serves that model, through an online service or a compatible local endpoint. An agent, such as Claude Code or Codex, uses a model and tools to work on your project.

Routing decides where a model request goes. Orchestration decides how agents divide a task. You can use either without the other: one agent can use a route, and several agents can each use a direct provider connection.

The route does not automatically know which model will do the best job. You choose a model, a saved alias or a configured route, and the gateway follows that configuration.

One connection, several choices

The basic flow looks like this:

Agent or coding tool
         ↓
Model or saved route
         ↓
 OmniRoute gateway
         ↓
  Provider account
         ↓
   Model response

That gives you one place to change the models and accounts behind a compatible tool's connection. A route might try a preferred model first and use a configured alternative when an eligible failure occurs. An alias can give a model a name you reuse across tools.

There is a practical cost: the gateway must be available. If it stops, requests that use it stop too. Direct agent connections keep their own configuration and availability.

Start with Connections

In Developer mode, open Settings, select the computer you want to configure, then choose AI & agents → Connections. The Routing provider keys & accounts disclosure holds the gateway's provider accounts, named keys and sign-in controls. Full gateway management belongs to Developer mode; Guided keeps the everyday model setup simpler.

Native agent sign-in and gateway sign-in are separate. Signing in to Claude Code or Codex does not silently copy that account's credentials into OmniRoute. Where Lyre offers reuse of a saved API-key connection, you explicitly choose the import. Otherwise, add a key or use the gateway's supported sign-in flow.

For a provider with several keys, Add keys lets you name each one and save them in order. If only some rows save, the form keeps the failed rows so you can retry them without creating the successful keys again.

Choose models and routes

Open AI & agents → Routing. The current layout has Models & routes, Activity and Settings; account setup stays in Connections.

Models & routes starts with Enabled models. On hosts that support model selection, the initial automatic selection contains up to five available models. Browse models lets you search and enable more. Your explicit selection is kept, including when you choose more than five.

Your routes shows saved aliases and routes, with their primary model and fallback count. Open a row to inspect its steps. Create or edit routes is where you change that configuration. The provider map and advanced routing controls remain available through their disclosures.

When the host reports OmniRoute ready, choose OmniRoute and an enabled model in a new conversation's provider and model picker. An existing direct-provider conversation keeps its current provider path. A compatible external coding tool also needs its own gateway configuration; opening the routing guide does not connect it.

What fallback actually means

There are two choices to distinguish: which model a route uses, and which account serves a request for that provider.

With First available key order, the gateway tries eligible keys in priority order. Disabled keys and keys still cooling down are skipped. Some account-level failures, such as authentication or quota problems, can allow another key to be tried. A configured model route can also contain fallback steps.

This is conditional recovery. An invalid request, a provider-wide failure or a pinned connection can stop account retries. There must be an eligible configured alternative, and it must be able to handle the request. Changing models can also change response quality, supported features and cost.

Fallback can send your prompt to another configured provider. Choose those destinations with the same care as your first choice, especially when the request contains project context.

Know what is happening

Activity shows the gateway's reported usage and request history. Its Live routing map is a secondary view of actual reported traffic. A diagram or a connected account alone does not prove that a request ran successfully.

Use the history to check which model and account served a request and whether it succeeded. Treat estimated cost and unknown quota information as estimates or unknowns, rather than a billing guarantee.

Where the gateway runs

Under Routing → Settings, Included with Lyre selects the Lyre-managed runtime on that computer. If the runtime is missing, the supported host offers Install OmniRoute. The page reports setup progress, readiness and failures, with the corresponding recovery action.

Start routing when this computer starts controls startup. Installation, running state and automatic updates are separate: a saved startup preference is not proof that the gateway is running. Available Start, Stop and update controls depend on the host version and your management access.

Use external connects to an operator-managed gateway. That gateway's address, availability and maintenance remain its operator's responsibility. When you configure routing from a phone or another client, you are configuring the selected computer's connection.

Gateway administration requires owner access. Keys stay with the host and gateway; list and history views do not reveal saved secrets. Hosted providers still receive the inference requests you send them. Routing through your computer does not turn an online model into an offline one.

Try one route first

Start with one connected provider and one enabled model. Send a small request, then check Activity. Add a second account or a fallback model when you have a specific reason, and inspect the route before relying on it.

That makes routing useful without making setup larger than the task. For a single account that already works, a direct agent connection may be all you need.

For the controls and recovery steps, see the Routing guide. For dividing a task among agents, read How orchestration works in Lyre.