config.yaml

When to use config.yaml, when not to, and how it interacts with environment variables and Docker.

The goal in GoModel is to make config.yaml optional as much as possible. Prefer environment variables for normal deployments, CI, containers, and secret injection.

Use config.yaml when you need structure that env vars cannot express cleanly, especially:

• per-provider resilience overrides
• custom provider instance names that do not fit the generated <provider-type>-<suffix> env naming
• richer reviewable provider model lists, especially when using allowlist mode
• reviewable budget limits by user_path
• larger nested config that is easier to review in one file

For multiple provider instances, env vars support <PROVIDER>_<SUFFIX>_API_KEY, <PROVIDER>_<SUFFIX>_BASE_URL, and <PROVIDER>_<SUFFIX>_MODELS. The suffix becomes a hyphenated provider name: OPENAI_EAST_API_KEY registers openai-east, and OLLAMA_A_BASE_URL registers ollama-a. Azure also supports <PROVIDER>_<SUFFIX>_API_VERSION.

Google Vertex AI is the exception to the provider-name shape: use VERTEX_* env vars to create type: vertex providers named vertex, vertex_us, vertex_eu, and so on. Vertex requires VERTEX_PROJECT and VERTEX_LOCATION; VERTEX_AUTH_TYPE defaults to gcp_adc.

Configured provider model lists can stay in env via <PROVIDER>_MODELS, for example OPENROUTER_MODELS, ORACLE_MODELS, AZURE_MODELS, or VLLM_MODELS. Set CONFIGURED_PROVIDER_MODELS_MODE=fallback (default) to use those lists only when upstream /models fails or is empty, or allowlist to expose only the configured models for providers that define a list and skip their upstream /models calls.

Priority Order

Effective precedence is:

1. environment variables
2. optional config/config.yaml or config.yaml
3. built-in defaults from code

.env is not a separate priority layer. It is just a convenient way to load environment variables before startup.

Current Schema

The current source of truth lives in the main codebase:

• config/config.go
• config/config.example.yaml

For deployments mounted below a domain root, set server.base_path or BASE_PATH. For example, BASE_PATH=/g serves the gateway at /g/v1/..., /g/admin/..., and /g/health.

Docker

GoModel reads config/config.yaml first, then config.yaml.

With docker run, you can keep a host file named config.yml and mount it to the in-container path GoModel expects:

docker run --rm -p 8080:8080 \
  -v "$PWD/config.yml:/app/config/config.yaml:ro" \
  enterpilot/gomodel:latest

With Docker Compose:

services:
  gomodel:
    image: enterpilot/gomodel:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.yml:/app/config/config.yaml:ro

If env vars and YAML both define the same setting, the environment variable wins.

Gotchas

Unresolved ${VAR} placeholders drop the provider

If ${OPENAI_API_KEY} appears in YAML but the env var is not actually set, the literal string ${OPENAI_API_KEY} ends up as the API key value. The credential filter detects the ${ substring and removes the provider entirely. This also applies if ${VAR} appears in the middle of the value, such as prefix-${OPENAI_API_KEY}. Always verify your env vars are exported before starting the process, or supply a default: ${OPENAI_API_KEY:-}.

Per-provider resilience can only come from YAML

The env-var override walk skips map fields. RETRY_MAX_RETRIES changes the global default for all providers but cannot target a single provider. Per-provider tuning requires a providers.<name>.resilience: block in config.yaml.

Partial YAML leaves the rest at defaults

YAML is unmarshalled onto a struct that has already been populated with built-in defaults. Only fields that appear in the file are written. Omitting max_backoff from resilience.retry leaves it at its built-in default; you do not need to repeat defaults you are happy with.