Model Hub

Model Hub is Avibe’s default local model gateway. It keeps upstream credentials and routing on your machine, lets several Agent backends share the same source, and moves a request to the next configured source when the current one can recoverably no longer serve it.

Model Hub routes your own models to your Agents on your machine. It is separate from Model Service, which supplies cloud models for Avibe features such as Voice input.

The Models page has three tabs:

Sources & gateway configures where models come from and how each Agent reaches them.
Usage shows calls metered by the Gateway. See Explore usage.
Subscription quota shows the limits of each subscription signed in as a gateway Source and what its use is worth at API prices. See Check subscription quota.

Open Models > Sources & gateway. The page has two parts:

Sources lists the subscriptions and API keys you own. It is an inventory, not a priority list.
Gateway shows each Agent backend and the effective Route chain for each model, inherited from default routing or saved as a manual override.

Choose gateway or direct mode

Gateway mode is the default on a fresh installation. An existing installation with no Model Hub configuration stays in Direct mode until you switch each backend from the Models page. The choice is per backend and reversible. Switching back to Direct keeps your Sources and Route chains, but that backend resumes using its own native configuration. A Native hop inside a Gateway Route chain is still Gateway mode: Avibe owns fallback and recovery for that chain.

Add a Source

Add a subscription

In Sources, select Add subscription and choose the vendor.
Choose where the credential stays.
Select Sign in and complete the vendor flow.

The recommended choice depends on the vendor:

Claude: Use natively is recommended. Claude Code uses its local login. You can explicitly choose Sign in as a gateway source to supply other Agents, but Avibe shows the account-restriction warning before sign-in.
ChatGPT: Sign in as a gateway source is recommended. It makes usage, quota, and takeover visible. Native Codex sign-in remains supported, but quota exhaustion will not trigger Gateway takeover and its usage stays outside Model Hub.

Each backend can have only one Native Source because its official CLI exposes one current login. Add additional accounts as gateway-held Sources. You can keep both channels by adding them one at a time.

Add an API key

Select Add API key.
Enter an optional name, a Base URL, and the API key. A custom Base URL can point to a relay, aggregator, or self-hosted compatible service.
Select Add. Avibe connects once, authenticates, identifies the interface, and fetches the model list before saving.

Fetch models runs the same check without saving anything. If Avibe connects but cannot identify the interface, choose a one-time interface hint and retry. The hint only changes probe order; Avibe still requires a successful response before it can save the Source. The identified interface is fixed after save. To change it, create a new Source. If the interface is identified but the model list does not return, you can retry or select Add anyway. The Source is saved without a discovered inventory, and you can add models manually from Source details.

Maintain the model list

After a Source is added, Avibe opens Source details > Models. From there you can:

Select Refetch to test the saved Source, update its health, and refresh discovered models. This is the only saved-Source refresh action.
Add a model manually when discovery cannot find it.
Edit the exact reasoning tiers accepted by any discovered or manual model. No tier is selected or filled by default.
Remove models you added manually. Models reported by the upstream are managed by refetch instead.

Refetch preserves manual models and the reasoning tiers you edited. Inventory changes can change automatic matching. If a change would remove effective hops or leave models without supply, Avibe shows the affected hops and models before asking you to confirm. A failed fetch keeps the last list the page actually read. For API-key Sources, the model list is matching evidence, not a list of the only models they may serve. A missing entry does not block an API-key request, and removing a manually added model does not delete a saved route. An explicitly retired Source/model pair cannot be used. Backend model support, Source compatibility, credentials, and health still apply; an unknown model does not acquire reasoning tiers that the Source has not declared for that exact model. Subscriptions, whether signed in as gateway Sources or used natively, keep their existing model support. They still participate in automatic matching and manual routes, but new or changed subscription hops must pass the existing model-list and retirement checks. Routing does not extend the models supported by the Gateway or native CLI for a subscription.

Configure default routing

In Gateway, choose a backend and open Default routing to select its default Sources and arrange their order. Models without a nonempty saved manual override follow these defaults; an empty saved chain also inherits them. Each effective Route chain is an ordered list of exact pairs: a Source and the upstream model it should call. For example, suppose two API-key Sources have the default order A, then B, and you request model-x. If only B lists model-x, the chain contains only B. If neither Source lists it, the chain is A, then B, using model-x unchanged at each hop. It does not try an unmatched A before a known match on B. Avibe first includes all eligible matches in default order, including matching subscriptions. Only when there are no matches does it use eligible default API-key Sources with the requested model ID unchanged. Subscriptions are not candidates for unknown-model passthrough. Native Claude matching recognizes its supported aliases and versions; other backends and API Sources use exact model IDs. Temporary unavailability does not turn a matched chain into passthrough. New models follow defaults automatically. Changes to default membership, order, or matching evidence update inherited routes; they leave saved manual chains unchanged. The dialog shows how many models inherit defaults and how many have saved overrides. Changes apply only to the selected backend. Select Save once to apply the default membership and order, including changes to inherited routes; there is no second affected-routes confirmation. Avibe still checks the exact impact with the server. If that impact changes while saving, the save stops and keeps your draft for retry. Removing a Source from defaults keeps manual routes that use it; deleting the Source itself removes its references through a separate guarded change.

Edit a model route

Open a model in Gateway to inspect its chain. For an inherited route, select Edit route to start a manual draft. You can:

add or remove a hop;
reorder hops;
change a hop’s explicit upstream model mapping, including an exact ID absent from an API-key Source’s model list; and
select Save to store a nonempty chain as a manual override.

Manual hops may use compatible Sources outside this backend’s defaults. Saving a nonempty chain creates a manual override, even if it is identical to the automatic result. An empty chain is treated as no override: saving it restores inherited routing, not a disabled model. If a configuration Save requires a Gateway restart, Avibe waits for existing request transfers, including streams, to finish or close before restarting. New requests wait while the change is applied; saving does not cut off an active stream. The first runnable hop is used. Avibe walks the remaining hops when a hop is already blocked, or when it hits a fallback-eligible quota, rate, upstream, or network failure before output begins. Blocked hops stay visible in their planned positions; temporary health changes do not reorder the chain or substitute another model.

On upgrade, empty routes saved by earlier versions follow current defaults, including those Avibe originally generated. Nonempty routes keep their exact hops and order as manual overrides, even if originally generated, identical to the automatic result, or using models no longer listed. Retaining a stale subscription hop does not bypass subscription model checks. Use Restore automatic to make a nonempty override follow current defaults.

Restore automatic routing

In the route dialog footer, select Restore automatic to preview the inherited chain. Removing the last hop from a manual draft opens the same restore preview. This changes only the draft, and the result may be Passthrough or Unconfigured. Undo restore brings back the preceding manual draft. On Save, Avibe checks the effective route’s impact and asks you to confirm if needed before removing the override and applying inherited routing. The saved route stays unchanged until saving succeeds. Cancel or closing the dialog writes nothing. If saving fails, the draft stays available to retry.

Read the status

Each model’s route badge explains where its chain comes from:

Badge	What it means
Automatic	Matching Sources form the chain in backend default order.
Manual	A nonempty saved override supplies the exact hops and order.
Passthrough	No eligible default Source has a match; eligible API-key defaults receive the requested model ID unchanged.

Hover over or focus a badge for its explanation, or tap it on touch devices without opening the route dialog. Escape or interaction outside the help dismisses it. These badges describe routing, not Source health or a guarantee that the upstream accepts the model; stopping the Gateway does not change the route’s origin. If inheritance produces no eligible hops, the model shows Unconfigured. This includes an unmatched model whose defaults contain only subscriptions. Use Configure default routing to choose eligible default Sources, or save a nonempty manual route. Health changes and request errors do not change the route’s origin. Source rows use these states:

What you see	What it means
Saved	Configuration is stored, but a successful model request with the current configuration has not yet been recorded. This is not an error or a health guarantee.
In use	The Source is included in at least one effective route.
Standby	The Source is healthy but is not currently supplying a configured route.
Unavailable · retrying automatically after …	Quota, rate, or network trouble put the Source in cooldown. Avibe retries after the shown delay.
Sign in again, Out of balance, Credential revoked, or Account restricted	The Source needs your action and will not recover by waiting.
Error	Avibe could not classify the failure. It will not clear automatically.

Saved uses neutral styling. Its connection hint explains the status; it does not ask you to repair anything. A successful model request updates pending verification. Actual cooldown, credential, or error states take priority over Saved. Each Gateway backend shows one supply status for its selected model:

What you see	What it means
Gateway · Healthy	The intended first hop is serving.
Gateway · Degraded	A later hop is serving, or part of the chain is blocked. Requests can still complete.
Gateway · All sources are cooling down	No hop is runnable yet, but every blocker will retry automatically.
Gateway · No source is available	The chain is empty or at least one blocker needs action.
Gateway · No model selected	The backend is in Gateway mode but has no selected model to summarize.

Taken over appears only when a recoverably unavailable first hop has handed the request to a later hop. A successful takeover is silent in the conversation. The Models page shows the current Source, the paused path, and the temporary replacement; the next turn returns to the first hop after it recovers, without changing your saved order.

Explore usage

Open Models > Usage to see calls metered by the Gateway. The trend appears above the details table.

Range	Chart
24 hours	An hourly line chart, including the current partial hour and the preceding 23 hours.
7 days	A daily line chart.
30 days or 60 days	A daily stacked bar chart.

The page displays the returned range and UTC offsets from the machine running Avibe. Hourly statistics begin with the version that records them. Older daily-only usage stays in daily totals; it is not redistributed into hourly counts. Hours it could belong to are marked incomplete, with the notice Includes historical usage without hourly time. This can cover adjacent dates when the old record has no time-zone information. Recorded hourly counts remain visible, but incomplete history is not a complete zero. Select one or more Sources or models to filter the summary, chart, and table together. Each Source is a configured account or API-key connection, so two accounts remain distinct even if they use the same vendor or display name. Choose all tokens, input, output, cache reads, or request count as the metric. Group token trends by token type, model, or Source, or show the total; request counts support total, model, and Source grouping. Model grouping keeps the same model on different Sources separate. Legend toggles change chart visibility, not the report filters. With more than six model or Source series, colors repeat; use their labels, details, or filters to distinguish them. Hover over or click a time point to see its exact figures. Clicking elsewhere closes ordinary details. The pin button in the detail corner explicitly pins or unpins the time point; pinned details remain visible when you click elsewhere, and the table shows that interval. Unpinning restores the table’s full filtered range. Escape closes the detail and clears any pin. Changing the range, filters, metric, or chart grouping also clears the pin. Keyboard users can focus a time point and press Enter or Space to reach the pin control. The table shows recorded counts grouped by model or Source. Select the active metric column header to reverse the sort order. Export CSV uses the current filters and any pinned interval, exporting bucket-level Source/model records rather than the table’s grouped or sorted layout. It includes time bounds and a history-completeness flag; unavailable token values are left blank. For unusually long Source IDs, the Source ID column can contain a shortened internal ledger key instead of the original ID.

Input already includes cached input. Total tokens are input plus output; token-type series split this into noncached input, cache reads, and output. The cache share is cached input divided by all input.Request count measures upstream calls, so one Agent turn can contribute several requests after fallback. Token counts depend on upstream reports: missing reports are not zero usage. Calls made outside the Gateway are not included.At API price is an estimate: the same usage priced at the vendor’s published API prices, not an amount charged. The page shows the date of the price table it used, and every day is priced at that current table. A figure marked ≥ is a lower bound: some requests reported no token counts, some usage has no price, or part of the history is incomplete. Models with no known price show No price yet; they are left out of the total, never counted as zero, and the left-out token count is shown. To add or correct a price, see Correct prices.

Check subscription quota

Open Models > Subscription quota to see every subscription signed in as a gateway Source. The page refreshes every five minutes; Refresh now reads it immediately. Each account shows its limits as the vendor reports them, such as the 5-hour and weekly limits and any per-model weekly limit, with the share used, when it resets, and whether the current pace lasts until the reset. If a reading fails, the page keeps the last one and says how old it is. A subscription that does not report quota says so. The page also values each account’s metered use at API price, the same estimate as Explore usage:

Last 7 days at API price covers the trailing seven days.
This cycle at API price covers the current billing cycle when the account has a renewal day set in the price override file. Otherwise the page shows Last 30 days at API price.
Paid back compares that period’s value with the plan’s monthly fee, as a multiple of the fee or as the amount still to pay back.

The monthly fee comes from the plan the vendor reports, or from the plan you set in the price override file. Built-in fees cover Claude Pro, Max 5x, and Max 20x, and ChatGPT Plus and Pro. When the plan is unknown, such as a Team or Enterprise seat, the page shows the value but no payback, and the summary leaves that account out of the payback total. A value marked ≥ is a lower bound, so its payback is at least the multiple shown. The page never states a shortfall over usage it could not price. Only calls through the Gateway are valued; use from other devices or apps on the same account still counts toward the vendor’s limits but not toward the value.

Correct prices

Prices come from the models.dev catalog that Avibe already caches for the model picker. To price a model the catalog does not list, correct a price, or set an account’s plan, create ~/.avibe/state/model_hub_prices.json. It is read on every page load, so changes apply the next time the page reads usage; no restart is needed. Entries in this file take precedence over models.dev. Every member is optional:

{
  "models": {
    "my-relay-model": {"input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75},
    "relay-alias": {"alias": "claude-sonnet-5"}
  },
  "plans": {"team_seat": {"fee_usd": 30}},
  "sources": {"src_abc123": {"plan": "team_seat", "renewal_day": 14}}
}

models is keyed by model ID. Prices are USD per 1 million tokens. input and output are required; cache_read, cache_write (five-minute cache), and cache_write_1h are optional. A missing cache_read or cache_write is priced as input, and a missing cache_write_1h as twice input. Instead of prices, an entry can give alias to use another model’s price. Model IDs are matched without a date suffix, a bracketed suffix such as [1m], or a provider/ prefix. Keys longer than 128 characters are ignored.
plans sets or adds a monthly fee in USD for a plan key. The built-in keys are claude_pro, claude_max_5x, claude_max_20x, chatgpt_plus, and chatgpt_pro.
sources is keyed by Source ID, as shown in the Source ID column of the Usage CSV export. Source IDs that Avibe creates look like src_abc123. If that column shows a shortened internal ledger key instead, the override cannot match it. plan sets the account’s plan and wins over the plan the vendor reports. It can be a built-in key, a key you added under plans, or a vendor plan name such as max 20x. renewal_day (1–31) sets the day of the month the billing cycle renews; a day past the end of a short month renews on its last day.

A value that is not a valid number in range, such as a negative, non-numeric, or extremely large price or fee, is ignored, and the rest of the file still applies. An invalid input or output drops that model’s entry, so the model keeps its models.dev price; an invalid optional price is treated as missing. If the whole file cannot be read, Avibe ignores it and prices from models.dev alone.

Understand errors and recover

Latest recorded turn

The route dialog checks the latest retained, settled turn that Avibe can attribute exactly to this backend and model. If it ended with a terminal error, Latest recorded turn shows the recorded time and historical Source/model. View error details opens that same record’s safe structured details, including the reason and, when available, HTTP status and an observed error code. Raw upstream messages and credentials are excluded. A later recorded success or cancellation, or no retained record, leaves no old error panel. Failed reads offer Retry. This is not a record of every request: OpenCode’s shared-process requests remain untracked when they cannot be attributed to an exact turn. Error codes depend on what the upstream protocol actually returns. An observed model_not_found gets a model-not-found explanation; a generic Anthropic not_found_error is not rewritten to that code. Without a specific code, the panel uses the recorded reason. Route badges and Source health are separate from these details.

Messages on the Models page

Message	What to do
Gateway component not installed · click to install	Open the confirmation, then install and start the component. No backend changes mode unless you switch it separately.
Gateway not started · click to start or Gateway not running	Start the Gateway, then retry the action. Route origin and draft previews remain available; they do not mean the Gateway is ready to serve requests.
Could not read the source list · the gateway itself is fine	Select Retry. Only the Source list failed; other Gateway state remains valid.
Could not read this backend’s supply · the gateway itself is fine	Select Retry for that backend. Do not add a Source merely because this read failed.
Authentication failed: 401 Unauthorized	Check or replace the API key, then retry.
Wrong address: 404 Not Found or Network unreachable: connection timed out	Correct the Base URL or network path, then retry.
Connected and authenticated — but we cannot tell which interface it speaks	Choose an interface hint and retry. Nothing is saved until a real response proves the interface.
The interface is identified — but its model list did not come back this time	Retry, or choose Add anyway and maintain the list manually.
Sign-in did not complete. You can retry.	Retry the vendor sign-in. Closing the dialog cancels the flow Avibe is tracking.
The fetch did not come back. The list below is the last one this page actually read	Keep working from the retained list or select Try again.

Messages in a turn

Situation	What Avibe reports	Recovery
The Route chain is empty	The requested model has no configured route and points you to Models.	Configure eligible backend defaults, or save a nonempty manual route. An empty override already inherits defaults.
Every hop is cooling down	A waiting message with the next recovery time.	Wait. Avibe retries automatically.
No hop can run and at least one blocker needs action	An interrupted message with the classified blockers.	Repair the named Source, or edit the Route chain.
The request itself is incompatible	This request is incompatible; switching Sources will not help.	Change the request, tools, parameters, or model rather than reordering Sources.
The upstream reports `model_not_found`	A model-not-found explanation when retained in Latest recorded turn. A Passthrough badge stays Passthrough; the error does not mark the Source unhealthy or trigger fallback.	Check the exact model ID and upstream support, then change the model or its route.
The local Gateway stops during a request	A Gateway-down error; if output had started, Avibe also says the output may be incomplete.	Restore the Gateway and retry. Avibe does not replay partial output or blame a Source.
A Source fails after output has started	If another hop is now current: The next turn has switched Sources; retry. Otherwise Avibe shows the same waiting or interrupted result as an exhausted chain.	Retry as a new turn. Avibe never replays a partially streamed turn.
You cancel the turn	The normal canceled-turn message, with no Model Hub supply message.	Start another turn when ready.

Recovery by cause

Cooldown or takeover: wait for the displayed retry time. Recovery and the return to the first hop are automatic and do not change the chain.
Expired subscription login: follow Sign in again for that Source.
Exhausted balance: top up with the vendor, then open Source details and select Refetch.
Revoked API key: replace the key in the existing Source, then refetch. The Source identity and every Route position stay intact.
Restricted account: follow the vendor remedy or move the affected model to another Source.
Unclassified Error: fix the suspected upstream problem, then use Refetch. A successful current check clears the blocker.
Model rejected by the upstream: verify the exact model ID and upstream support, then edit the model or route. Absence from an API-key Source’s fetched list alone does not mean the model is unusable; subscriptions retain their existing model checks.
Source missing: edit the Route chain. Adding a new Source does not repair a hop that refers to the removed Source.
Native CLI unavailable: restore the backend’s local CLI and login, then retry.
Need an immediate escape hatch: switch only the affected backend to Direct. Your Sources and Route chains remain saved for when you switch back.

Start here

avibe.bot Cloud

Self-hosting

Platforms

Agents

Concepts

Reference

Compare

Choose gateway or direct mode

Add a Source

Add a subscription

Add an API key

Maintain the model list

Configure default routing

Edit a model route

Restore automatic routing

Read the status

Explore usage

Check subscription quota

Correct prices

Understand errors and recover

Latest recorded turn

Messages on the Models page

Messages in a turn

Recovery by cause

​Choose gateway or direct mode

​Add a Source

​Add a subscription

​Add an API key

​Maintain the model list

​Configure default routing

​Edit a model route

​Restore automatic routing

​Read the status

​Explore usage

​Check subscription quota

​Correct prices

​Understand errors and recover

​Latest recorded turn

​Messages on the Models page

​Messages in a turn

​Recovery by cause

Choose gateway or direct mode

Add a Source

Add a subscription

Add an API key

Maintain the model list

Configure default routing

Edit a model route

Restore automatic routing

Read the status

Explore usage

Check subscription quota

Correct prices

Understand errors and recover

Latest recorded turn

Messages on the Models page

Messages in a turn

Recovery by cause