Variants

Field reference for Surface Variants and override settings: named surface variations selectable at request time.

A Surface Variant is a named, switchable snapshot of an Agent Surface stored as a sparse delta over the base surface. Variants are selected at request time by appending $alias to the surface route.

https://<GATEWAY_HOST>/<route>$<alias>/<optional-path>

When no $alias is present, the gateway uses the default variant (the base surface, unless a Default Variant is set in the surface settings).

Variant fields

FieldTypeRequiredDefaultDescription
Variant IDstring (UUID)Yes—Stable internal identifier. Survives renames of alias and name. Referenced by the Default Variant setting on the surface.
AliasstringYes—URL-safe alias used in the route path. Must match ^[a-z0-9-]{1,32}$ (lowercase letters, digits, dashes; max 32 characters). Must be unique within the surface.
NamestringYes—Human-readable name shown in the dashboard.
DescriptionstringNo""Free-text description.
EnabledboolNotrueWhether this variant accepts traffic. A disabled variant returns HTTP 503, not 404, so callers can distinguish “intentionally off” from “does not exist”.
OverridesOverride settingsNoEmptySparse or complete delta applied over the base surface at resolve time.

Alias grammar

The alias must satisfy ^[a-z0-9-]{1,32}$:

  • Lowercase ASCII letters, digits, and dashes.
  • No underscores, dots, or uppercase.
  • Between 1 and 32 characters.
  • Must be unique across all variants on the same surface.

Validation is enforced server-side. Malformed aliases are rejected on create and update.

Lifecycle states

StatusRequest behaviour
Active (enabled: true)Variant is active and serves traffic.
Disabled (enabled: false)Variant exists but returns HTTP 503. Useful for temporarily disabling a variant without deleting it.

Override settings

The Overrides configuration holds a delta applied over the base surface at variant resolution time. Two merge modes are available: sparse merge (default) and complete snapshot.

FieldTypeRequiredDefaultDescription
Override modetoggleNoSparse mergeMerge mode selector. See Merge modes.
Access PointAccessPointOverridesNoNoneAccess point delta. Cannot override Listener address, Channel Route, or Protocol; these are surface-level identifiers.
Managed AgentTargetOverridesNoNoneTarget delta.
Outbound ListenerTransitOverridesNoNoneTransit delta.
Agent IdentitySurfaceIdentitySlotsNoNonePer-variant identity slot bindings. When set, replaces the base surface’s identity slots wholesale. Slots are independent per variant, so rotating a credential in one variant does not affect others.
Credential DelegationOutboundCredentialBinding[]NoNonePer-variant outbound credential bindings. When set, replaces the base surface’s credential delegation list wholesale.

Merge modes

Sparse merge (default)

A field with no value set on the variant means “inherit from base”. A field with a value set means “use this value”. The variant only needs to specify fields it wants to override; all others come from the base surface.

Use sparse merge for variants that differ only in one or two aspects, for example a staging variant that overrides only the target endpoint.

Complete snapshot

Every overridable field is wholesale-replaced from the override, including fields set to no value (which clear the base value). Surface-level identifiers (Listener address, Channel Route, Protocol, and the outbound listen address) are still carried from the base; variants cannot change those.

Use complete snapshots when the variant was created as a full copy of the surface at a point in time and must not silently inherit later base edits.

Access Point overrides

A subset of Access Point fields that a variant can override. The following fields cannot be overridden and are always inherited from the base:

  • Listener address
  • Channel Route
  • Protocol

All other Access Point fields are overridable per variant.