config.yml reference: all MonoRelay configuration options

MonoRelay is configured through a single config.yml file located in the project root. When the file changes on disk, MonoRelay detects the modification via watchfiles and reloads the configuration in place — no restart required. The server, routing rules, provider keys, and all other settings are applied to the next incoming request immediately after reload.

Full config structure

The annotated skeleton below shows every top-level section. Each section is optional; MonoRelay applies sensible defaults for any key you omit.

config.yml

# ── Server ─────────────────────────────────────────────────────────────────
server:
  host: "0.0.0.0"          # Bind address
  port: 8787               # Listening port
  access_key: "change-me"  # Bearer token required on all requests
  access_key_enabled: true # Set false to disable key auth entirely
  log_level: "INFO"        # DEBUG | INFO | WARNING | ERROR
  cors_origins:
    - "*"
  public_host: ""          # Public IP/domain for API URL generation
  jwt_secret: ""           # Secret for JWT session tokens (SSO)

# ── Providers ──────────────────────────────────────────────────────────────
providers:
  openrouter:
    enabled: true
    base_url: "https://openrouter.ai/api/v1"
    keys:
      - key: "sk-or-v1-..."
        label: "main"
        weight: 1
    rate_limit_cooldown: 60
    timeout: 120

# ── Model routing ──────────────────────────────────────────────────────────
model_routing:
  enabled: true
  mode: "passthrough"
  aliases: {}
  provider_mapping: {}
  model_overrides: {}
  complexity:
    enabled: false
  cascade:
    enabled: false
  payload_transformation:
    enabled: false

# ── Key selection ──────────────────────────────────────────────────────────
key_selection:
  strategy: "round-robin"  # round-robin | random | weighted

# ── Tool calling ───────────────────────────────────────────────────────────
tool_calling:
  auto_downgrade: true
  unsupported_models: []

# ── Request logging ────────────────────────────────────────────────────────
logging:
  enabled: true
  db_path: "./data/requests.db"
  max_age_days: 30
  content_preview_length: 200

# ── Single sign-on ─────────────────────────────────────────────────────────
sso:
  enabled: false
  provider: "github"       # github | google | prismaauth
  sso_only: false

# ── GitHub Gist sync ───────────────────────────────────────────────────────
sync:
  enabled: false
  gist_id: ""
  gist_id_stats: ""

Top-level sections

Key	Purpose
`server`	Network binding, access key, CORS, JWT, log level
`providers`	One entry per upstream AI provider (OpenRouter, NVIDIA, OpenAI, etc.)
`model_routing`	Aliases, provider mapping, complexity routing, cascade fallback
`key_selection`	Strategy used to pick among multiple keys for a provider
`tool_calling`	Auto-downgrade for models that do not support function calling
`logging`	SQLite request log, retention window, preview length
`sso`	OAuth / OIDC single sign-on (GitHub, Google, PrismaAuth)
`sync`	Push/pull config and stats to a private GitHub Gist

`server` section parameters

Parameter	Type	Default	Description
`host`	string	`"0.0.0.0"`	Network interface to bind
`port`	integer	`8787`	TCP port
`access_key`	string	(auto-generated UUID)	Bearer token for all API requests
`access_key_enabled`	boolean	`true`	Toggle key authentication on or off
`log_level`	string	`"INFO"`	Python logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`cors_origins`	string[]	`["*"]`	Allowed CORS origins; accepts exact origins or `"*"`
`public_host`	string	`""`	Public hostname used when generating API base URLs; auto-detected when empty
`jwt_secret`	string	`""`	Secret key for signing JWT session tokens used by the SSO flow

If access_key is left blank in config.yml, MonoRelay generates a random UUID at startup and logs it. Set an explicit key before exposing the server on a public network.

Hot-reload

MonoRelay watches config.yml with watchfiles. When a change is detected the config is reloaded atomically — in-flight requests are not interrupted. Saves performed through the management API use an atomic rename (write to a temp file, then replace) to prevent the watcher from reading a partial file.

You can trigger a reload manually by saving the file with no changes (e.g., touch config.yml).

Configuring AI providers — add and tune each upstream provider
Model routing and aliases — control which model goes to which provider
API key rotation and rate limiting — manage multiple keys per provider

Get Started

Configuration

Admin Dashboard

Authentication

config.yml reference: all MonoRelay configuration options

Full config structure

Top-level sections

`server` section parameters

Hot-reload

​Full config structure

​Top-level sections

​server section parameters

​Hot-reload

​Related pages

Full config structure

Top-level sections

`server` section parameters

Hot-reload

Related pages