Nautili
Documentation

Routing Profiles

The named bundle that decides which model a request gets when it names none -- its fields, its binding ladder, and how the rungs merge.

Routing Profiles

A routing profile is behaviour: which model, which provider order, which fallbacks, how much the gateway may rewrite. A guardrail is protection: who may use what, and how much.

They attach through the same ladder, but they resolve differently -- and that difference is the single most important thing to understand about profiles.

A guardrail resolution picks one whole guardrail, most specific wins. A profile resolution merges every applicable rung field by field, so an issued key can override one setting while inheriting the rest of its team's configuration.

The ladder

RungBound to
1. Team defaultThe team, as a fallback for every principal without a more specific binding.
2. IdentityA person.
3. Issued keyOne key.
4. dz_routerOne request. See Per-request override.

Most specific wins per field. The merge happens in the backend, because only it knows which identity owns a key -- and because one implementation of the precedence rule is the only way it stays one rule.

An owned key is treated as both itself and its owner, so a key belonging to a person inherits that person's identity rung as well as the team default.

The fields

Every field is three-valued: set, or absent meaning inherit.

FieldValuesNotes
Default modelAn author/slug idUsed when a request names no model. Absent means this rung configures no default.
Fallback modelsAn ordered list, at most 4Tried in order, only when the model above cannot be served.
Rank providers bycost, latency, throughputDevZero's own vocabulary, translated at the connector.
Preferred providersAn ordered listTried before any other eligible endpoint.
Allowed providersA listOnly these may serve. Blank means no restriction.
Denied providersA listThese never serve. A provider cannot be both allowed and denied.
Auto enabledYes / no / inheritSee Auto mode.
Auto cost/quality dial0-100 leans entirely on quality, 10 always takes the cheapest. When no rung sets one, the resolver supplies the midpoint, 5. 0 is a real value, not "unset".
Models auto may pick / may never pickPatterns, at most 32 eachauthor/slug exactly, author/prefix*, author/*, or bare *.
UpstreamA connector idWhich upstream serves this scope. Absent means no preference.
Delegationdelegated, routerWho chooses this scope's serving path: delegated leaves it to the upstream's own router, which picks the provider and walks any fallback; router has the gateway's router choose one serving path and ask the upstream for exactly it, with the upstream's own fallback off. A ladder no rung configures resolves to delegated.
EligibilityA rule: conditions on serving-path attributesWhich serving paths this scope consents to. Unlike every other field it merges narrow-only down the ladder: a key or identity rung can only tighten what its team allowed, and an attempt to widen is ignored and recorded. Enforced only where delegation is router.
Custody orderown_first, managed_firstWhich custody arm a request with unstated custody tries first where the router chooses the serving path: the team's own credential's paths with DevZero's managed custody as overflow, or the reverse. A key bound to one arm never crosses it. A ladder no rung configures resolves to own_first.

An empty list means inherit, not "explicitly none". There is deliberately no way to express "blank what my team configured" -- if you need a scope with no fallbacks under a team that has some, that is not expressible today.

The upstream field is not a credential field

upstream says where the request egresses. Custody says whose money pays, and it stays a property of the issued key.

A profile naming an upstream the installation has not enabled is refused with 502 unknown_upstream, with no silent substitution.

The backend validates this field for shape only. It cannot see which connectors the gateway in front of your team has registered, so a typo is caught at request time rather than at save time.

What the resolver reports back

Alongside the merged fields, the resolution says where the default model came from -- the team default, an identity, or a key. That is what makes "why did I get this model?" answerable.

It also reports every profile that contributed, least specific first, and a version stamp taken from the newest contributor.

There are deliberately no per-field source labels for the four provider fields: they merge independently of each other, so a single source label would be a lie and four more would be noise.

Editing a profile

An update writes every field -- it is a full replace, not a patch. If you drive the API yourself, read-modify-write, or an omitted field is blanked.

How long an edit takes to reach traffic is bounded by the gateway's profile-freshness window. Two things make an edit safe mid-flight:

  • The router pins its first decision per session, so a conversation already under way keeps its model.
  • Nothing is ever substituted for a model a request named explicitly.

Archiving a profile is a soft delete.

On screen

The Profiles wizard has four zones:

  1. Name it, attach it. Every routing field starts as inherit.
  2. Default model and fallbacks. Blank means inherit from the rung above.
  3. Providers, auto, provider choice, custody order, eligibility. All inherit until touched. The copy states the important caveat in place: these are preferences we pass on, not guarantees -- the provider that actually served each request is recorded on it.
  4. What this profile will do. A pre-flight echo of the server's own rules.

A firing watch on the profile's scope surfaces as a marker inside the wizard.

On this page