Variants

Field reference for Surface Variants: named surface snapshots selectable at request time via $alias.

A Surface Variant is a named, switchable snapshot of an Agent Surface. Each variant holds a full independent copy of the surface configuration: Access Point settings, Managed Agent settings, Transit Points, policy, identity, networking, and payment. Variants are selected at request time by appending $alias to the surface route. Use variants to route test traffic through a staging configuration, offer partners a customised view of the same agent, or run A/B experiments without duplicating the base surface.

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

When no $alias is present, the gateway routes to the default variant. The base is the default unless a named variant has the Default toggle on.

Variant fields

FieldTypeRequiredDefaultDescription
Variant IDstring (UUID)Auto-generated—Stable internal identifier. Auto-assigned on creation. Survives renames of alias and name. Never editable in the panel.
NamestringYes—Human-readable name shown in the dashboard and in the variants widget on the canvas.
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.
DescriptionstringNo""Free-text description.
EnabledtoggleNoOnWhether this variant accepts traffic. A disabled variant returns HTTP 503, not 404, so callers can distinguish “intentionally off” from “does not exist”. The default variant cannot be disabled; promote another variant to default first.
DefaulttoggleNoOffWhen on, alias-less requests route to this variant instead of the base. One variant can be default at a 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
ActiveVariant is active and serves traffic.
DisabledVariant exists but returns HTTP 503. Use this to temporarily pause a variant without deleting it. The default variant cannot be disabled.

The base variant

The base row is always present in the Variants panel. It represents the unmodified surface with no variant overlay applied. The base:

  • Has no alias and cannot be given one.
  • Cannot be renamed or disabled.
  • Is the implicit default when no named variant has the Default toggle on.

Requests with no $alias token route to whichever variant has the Default toggle on. If no named variant is set as default, requests route to the base.

Configuring a variant

Variant configuration is managed on the canvas, not inside the Variants panel. The panel only manages the variant list (name, alias, enabled/default status).

To configure what a variant does:

  1. Open the Variants panel and add the variant if it does not exist yet.
  2. Switch to the variant using the variants widget in the surface builder.
  3. Edit elements on the canvas: Access Point settings, Managed Agent settings, Transit Points, Policy, Networking, Payment, and Identity elements, exactly as you would for the base surface.
  4. Switch back to base or another variant to restore that state.

Each variant maintains its own independent canvas state. Surface-level identifiers are always inherited from the base and cannot vary per variant:

  • Listen address
  • Channel Route
  • Protocol
  • Outbound listen address