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
  • data_sharing.backend_url is normalized to a versioned backend base URL and falls back to the gateway default when omitted
  • hot reload reconciles provider translators, routing, retries, cache, rate limits, model selection, collector behavior, and remote control in-place
  • server listener settings such as bind address, port, and HTTP timeouts still require 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
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, gateway identity, geo tags, and remote control data_sharing

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

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
  • retry.enabled: true
  • logging.level: info
  • logging.format: console
  • model_selection.enabled: false
  • data_sharing.enabled: false
  • data_sharing.backend_url: gateway default LunarGate backend base URL

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 hot reload makes config changes easy to apply but does not protect you from bad routing logic.