⚙️ Configuration Basics

Tresor is configured entirely via a single YAML file. All settings, downstreams, rules, and aliases live in one portable file that can be version-controlled and shared across environments.

📐 Config File Structure

# --- Server Settings ---
bind_addr: "127.0.0.1:11510"         # TCP address for gateway + admin API
socket_path: "/tmp/tresor.sock"      # Optional Unix socket (admin only)
db_path: "./tresor.db"               # SQLite database path
admin_password: "secret"             # 🔐 Optional Bearer token for admin API

# --- Proxy Settings ---
proxy_mode: "auto"                   # Outbound proxy behavior
proxy_api_keys:                      # 🔑 Optional: authenticate incoming proxy requests
  - sk-proxy-123

default_tab: "downstreams"           # Default web UI tab on load

# --- LLM Provider Endpoints ---
downstreams:
  - id: openai
    name: OpenAI
    api_formats: [openai]            # API format(s) this downstream speaks
    base_url: https://api.openai.com/v1
    api_key: sk-proj-...
    output_model_ids:                # Models this downstream can handle
      - gpt-4o
      - gpt-4o-mini

  - id: anthropic
    name: Anthropic
    api_formats: [anthropic]
    base_url: https://api.anthropic.com
    api_key: sk-ant-...
    output_model_ids:
      - claude-sonnet-4-20250514

# --- Routing Rules (Optional) ---
rules:
  - id: chat-rule
    name: Chat Completions
    pattern_path: /v1/chat/completions
    match_format: [openai]           # 🔌 Only match OpenAI-format requests
    match_downstreams: [openai]      # Only match the "openai" downstream
    pipeline_config:
      - plugin_id: custom_header
        config:
          headers:
            X-Custom-Header: my-value
    is_enabled: true

# --- Model Aliases ---
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-.*"
    options:
      - id: alias-claude-wildcard
        downstream_id: anthropic
        output_model_id: claude-sonnet-4-20250514
        is_regex: true

🖥️ Server Settings

Field	Type	Description
bind_addr	string	TCP address for the gateway and admin API (e.g. 127.0.0.1:11510)
socket_path	string	Optional Unix Domain Socket path for admin API only
db_path	string	SQLite database file path (~ expands to home directory)
admin_password	string	🔐 Optional Bearer token required for admin API and web UI access

🌐 Proxy Settings

Field	Type	Description
proxy_mode	string	Outbound proxy mode: auto, env, windows, or none
proxy_api_keys	list	🔑 Optional Bearer tokens that client requests must include
default_tab	string	Default web UI tab: downstreams, aliases, rules, plugins, settings, logs, or about
log_level	string	Request log verbosity: debug, info, warn, or error (default: info)

🔌 Downstream api_formats

The api_formats field declares which API protocol(s) a downstream speaks (e.g., openai, anthropic). This enables auto-translation: when a request arrives in a format that doesn't match the downstream's declared format, Tresor automatically inserts the appropriate format converter into the pipeline — no explicit rule needed.

For example, if a downstream declares api_formats: [anthropic] and receives a request at /v1/chat/completions (OpenAI format), Tresor automatically prepends the openai2anthropic transformer.

🏷️ Alias Option Fields

Each alias option within a group has these fields:

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 (default: false)

When is_regex: true, the group's input_model_id is a Go regular expression pattern. Requests whose model name matches the pattern are routed through this alias. See Model Aliases for details.

Alias groups are ordered by their position in the YAML array. In the web UI, groups can be reordered via drag-and-drop.

🔄 Upsert on Startup

On startup, Tresor upserts YAML data into SQLite:

• ➕ New rows (IDs not in DB) are inserted
• 🔄 Existing rows (matched by ID) are updated with YAML values
• 💾 DB-only rows (not in YAML) are preserved — this means you can manage everything from the web UI or CLI and your changes persist across restarts

↩️ YAML Write-Back

Every mutation made via the web UI or admin API (creating, updating, or deleting downstreams, aliases, or rules) triggers an atomic write back to the YAML config file. This keeps the config file in sync with runtime state — no manual editing needed after initial setup.

The write-back uses a tmp-file-plus-rename pattern for atomicity, so you never see a partially written config. ✨

➡️ Next Steps

• 🔗 Downstreams — Configure LLM provider endpoints
• 📏 Rules — Define routing rules with transform pipelines
• 🏷️ Aliases — Set up model name mappings
• 🌐 Proxy Modes — Configure outbound proxy behavior