🏷️ Model Aliases

Aliases let you map one model name to another at the gateway layer. Your application sends requests using its native model name (e.g., gpt-4o), and Tresor transparently forwards them to a different provider with a different model (e.g., claude-sonnet-4).

Aliases are the primary routing mechanism — they take priority over downstream output_model_ids matching. Rules only apply when no alias exists.

🔄 How Aliases Work

Aliases are organized into groups by input model ID. Within each group, you can define multiple options (different providers or models), and exactly one option is active at a time.

aliases:
  - input_model_id: gpt-4o           # Group: all mappings for "gpt-4o"
    options:
      - id: alias-gpt4o-openai
        downstream_id: openai
        output_model_id: gpt-4o       # ✅ Active (first in list)

      - id: alias-gpt4o-anthropic
        downstream_id: anthropic
        output_model_id: claude-sonnet-4-20250514

When your app sends a request for gpt-4o:

• ✅ Active alias is alias-gpt4o-openai → Request goes to OpenAI as gpt-4o (no transformation needed)
• 🔄 Switch active to alias-gpt4o-anthropic → Same request goes to Anthropic as claude-sonnet-4, with the model name rewritten in the request body

📊 Alias Group Semantics

• 🥇 The first option in each group is active by default (is_active is managed by the database, not YAML)
• 🔄 Activating one alias automatically deactivates any currently active sibling in the same group
• ⬆️ Deleting the active alias auto-promotes the next sibling to active
• 📭 Deleting the last alias in a group leaves no active alias (requests fall through to downstream output_model_ids matching)

⚡ Hot-Switching

You can switch the active alias for a model without restarting the daemon. The change takes effect immediately for subsequent requests:

# Switch gpt-4o to route through Anthropic
./tresor alias activate alias-gpt4o-anthropic

# Switch back to OpenAI
./tresor alias activate alias-gpt4o-openai

The web UI also provides activate buttons for each alias option in its group.

📐 Configuration Format

In YAML, aliases use a nested structure with input_model_id as the group key and options as the list of mappings:

aliases:
  - input_model_id: gpt-4o
    options:
      - id: alias-gpt4o-openai
        downstream_id: openai
        output_model_id: gpt-4o
      - id: alias-gpt4o-anthropic
        downstream_id: anthropic
        output_model_id: claude-sonnet-4-20250514

  - input_model_id: claude-sonnet
    options:
      - id: alias-sonnet-anthropic
        downstream_id: anthropic
        output_model_id: claude-sonnet-4-20250514

Each option requires:

Field	Required	Description
id	Yes	Unique identifier for this alias option
downstream_id	Yes	Which downstream provider to forward to
output_model_id	Yes	The model name to use when forwarding
is_regex	No	Treat input_model_id as a regular expression pattern

🎯 Regex Aliases

When is_regex: true, the input_model_id is interpreted as a Go regular expression. The alias matches any incoming model name that satisfies the pattern, rather than requiring an exact string match.

aliases:
  - input_model_id: "^claude-.*"
    options:
      - id: alias-claude-wildcard
        downstream_id: anthropic
        output_model_id: claude-sonnet-4-20250514
        is_regex: true

This example maps any model starting with claude- (e.g., claude-sonnet-4, claude-opus-4, claude-haiku-4.5) to Claude Sonnet on Anthropic.

Key behaviors:

• Exact-match aliases take priority over regex aliases. A request for claude-sonnet with an exact alias and a regex alias ^claude-.* will use the exact match.
• Regex aliases are excluded from the model discovery API (/v1/models, /models). Since they represent patterns rather than concrete model IDs, including them would mislead clients about available models.
• Invalid regex patterns are rejected at creation time. The alias won't be saved if the pattern can't be compiled.

🔃 Group Reordering

Alias groups are displayed in the order they were created. You can reorder groups via drag-and-drop in the web UI (drag a group's header to a new position). The order is persisted to the database (group_order column) and survives restarts.

In YAML, group ordering is determined by array position — the first group in the aliases array has group_order: 1, the second has group_order: 2, etc.

🛠️ Managing Aliases

🖥️ Via Web UI

The Aliases tab displays group cards showing each input model's options. You can:

• Create new alias groups with a tag-based model multi-select
• Add options to existing groups
• Click inactive options to hot-switch (activate them)
• Delete individual aliases or entire groups

💻 Via CLI

# List all alias groups with their active option highlighted
./tresor alias list

# Create a new alias option
./tresor alias create gpt-4o anthropic claude-sonnet-4-20250514

# Activate an alias (deactivates siblings in the same group)
./tresor alias activate alias-gpt4o-anthropic

# Delete an alias option
./tresor alias delete alias-gpt4o-openai

🌐 Via Admin API

Method	Path	Description
GET	/api/aliases	List all alias groups (enriched with downstream names, ordered by group_order)
POST	/api/aliases	Create a new alias option (body may include is_regex)
GET	/api/aliases/{id}	Get a single alias
PUT	/api/aliases/{id}	Update alias fields (including is_regex)
DELETE	/api/aliases/{id}	Delete an alias (auto-promotes sibling if deleting active)
PUT	/api/aliases/{id}/activate	Hot-switch: activate this alias, deactivate siblings
DELETE	/api/aliases/group/{inputModelId}	Delete all aliases for an input model
POST	/api/aliases/reorder	Reorder groups: {"order": ["gpt-4o", "claude-sonnet"]}