Skip to content

Configuration overview

YAML reference

LunarGate configuration is YAML-based, hot-reloadable, and environment-variable friendly. The gateway loads one config file, applies defaults, expands `${ENV_VAR}` placeholders across all string fields, and then uses the result to build providers, routing, retries, observability, and the rest of the runtime behavior.

The mental model:

  • providers tells the gateway what upstreams exist
  • routing decides which upstream handles a request
  • model_selection enriches requests so routing can act on complexity or skill
  • the rest of the sections shape operational behavior like retries, caching, logging, and Dashboard export

Start with providers
Define real upstreams, credentials, base URLs, and model discovery behavior.

Then wire routing
Choose how requests match routes, targets, fallback chains, and balancing strategies.

Need autorouting?
Jump to the lunargate/auto technique and then come back to model_selection.

How config loading works

  • the gateway reads the config file you pass with --config
  • it also tries to load a .env file from the config directory and then from the current working directory
  • ${ENV_VAR} expansion works across all string fields in the parsed config, not just provider API keys
  • general.api_key is the shared gateway identity key used by observability and remote control
  • general.backend_url is normalized to a versioned backend base URL and falls back to the gateway default when omitted
  • hot reload builds provider translators, routing, and model selection as one coherent generation and publishes it atomically; retries, cache, rate limits, inbound auth, logging, collector, remote control, and update checks reconcile separately
  • an HTTP API request keeps the runtime generation captured at handler entry, while a Responses WebSocket keeps the generation captured at connection setup
  • server listener settings such as bind address, port, and HTTP timeouts still require a process restart
  • logging level reloads live, but changing the logging output format requires a process restart
  • most operational sections have sane defaults, so a minimal config can stay very short

Top-level sections

Section What it controls Detailed page
general shared gateway identity key and control-plane backend URL for Dashboard integrations data_sharing
server bind address, port, and HTTP timeouts server
providers upstream providers, credentials, base URLs, model discovery, and default models providers
routing route matching, targets, balancing strategy, and fallback chains routing
model_selection complexity scoring, output headers, and autorouting inputs model_selection
rate_limiting in-memory throttling for inbound requests rate_limiting
caching in-memory exact-match response cache caching
retry retry policy for upstream failures retry
logging log level and output format logging
security config shape for inbound API keys; still not the primary hardening layer security
data_sharing Dashboard observability export, geo tags, and remote control data_sharing
update_check automatic release checks and their network behavior update_check

Minimal config

This is enough to start a single-provider gateway:

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"

routing:
  routes:
    - name: "default"
      targets:
        - provider: openai
          model: gpt-5.2
          weight: 100

Defaults worth knowing

These defaults are applied by the config manager if you omit them:

  • server.host: 0.0.0.0
  • server.port: 8080
  • server.read_timeout: 30s
  • server.write_timeout: 0s
  • server.idle_timeout: 60s
  • routing.default_strategy: round-robin
  • rate_limiting.enabled: false
  • caching.enabled: false
  • caching.max_entry_bytes: 16777216 (16 MiB)
  • caching.max_bytes: 67108864 (64 MiB)
  • retry.enabled: true
  • logging.level: info
  • logging.format: console
  • model_selection.enabled: false
  • general.api_key: empty
  • general.backend_url: gateway default LunarGate backend base URL
  • data_sharing.enabled: false
  • update_check.enabled: true

If you are just getting started:

  1. Read providers to define the upstreams the gateway can actually call.
  2. Then read routing to decide how requests are matched and where they land.
  3. Add data_sharing only if you want observability in the LunarGate Dashboard on app.lunargate.ai.

If you want lunargate/auto:

  1. Read model_selection to understand the scoring and emitted headers.
  2. Then read the lunargate/auto technique page for the conceptual routing pattern.
  3. Study the runnable python-auto-tiers-poetry example if you want to see the full pattern end to end.

Authoring tip

Tip

Keep specific routes above generic ones, keep provider IDs consistent between providers and routing.targets, and remember that the atomic runtime generation covers providers, routing, and model selection rather than every configuration section. Hot reload makes config changes easy to apply but does not protect you from bad routing logic.