Secret References

A secret reference tells GoModel where to read a value instead of holding the value itself:

server:
  master_key: ${file:/run/secrets/gomodel-master-key}

providers:
  openai:
    type: openai
    api_key: ${env:OPENAI_KEY}

References work in any string setting of config.yaml, in the environment variables that set those settings, and in provider environment variables:

OPENAI_API_KEY='${file:/run/secrets/openai}'
POSTGRES_URL='${file:/run/secrets/postgres-url}'

Single-quote the value in a shell so the shell does not expand it; .env files need no quoting. Docker Compose interpolates ${...} in its own files, so write $${file:...} there; Compose passes ${file:...} on to GoModel.

Syntax

A reference is ${<scheme>:<reference>}. It may sit inside a larger value, and one value may hold several:

providers:
  openai:
    type: openai
    api_key: ${env:OPENAI_KEY}
    proxy_url: http://gomodel:${file:/run/secrets/proxy-pass}@proxy:3128

mcp:
  servers:
    github:
      url: https://mcp.example.com/mcp
      headers:
        Authorization: Bearer ${env:GITHUB_TOKEN}

The resolved value is used as-is. It may contain newlines, quotes, or any other bytes, so a service-account JSON file works, and it is never scanned for further references.

Schemes

Scheme	Reference	Value
`env`	variable name	the variable’s value; unset or empty stops startup
`file`	absolute path	the file’s contents with one trailing newline removed; at most 1 MiB

file reads Docker and Kubernetes secret mounts directly, so no entrypoint script is needed to copy them into environment variables. env differs from the plain ${NAME} form in two ways: it is strict, and it works in environment variables, not only in config.yaml. The plain form is unchanged: ${NAME} and ${NAME:-default} are expanded in config.yaml, and an unset ${NAME} is left in place, which drops a provider whose key it is. External secret managers (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault) plug in as further schemes with GoModel Pro.

Failures stop startup

A reference that cannot be resolved stops the gateway with an error naming the setting and the scheme, never the value:

failed to resolve secret references: providers.openai.api_key: secret reference ${file:...}: open /run/secrets/openai: no such file or directory

A provider API key set by an environment variable is reported under the variable’s name, for example OPENAI_API_KEY_2: secret reference ${file:...}. A failed reload keeps the running configuration. GoModel never starts with, or sends upstream, an unresolved reference. Only values in use are resolved: a provider value in config.yaml that an environment variable overrides, a provider environment variable that GoModel ignores (for example OPENAI_MODELS when several openai providers exist and none is named openai), or a provider skipped for missing credentials, is not looked up.

Literal `${`

Write $${ for a literal ${. pa$${x} becomes pa${x}.

Limits

References are resolved once, when the configuration is loaded or reloaded. Rotating a secret takes a reload (gomodel --reload or SIGHUP).
They apply to string settings. A boolean or number setting cannot be a reference, and an environment variable that GoModel parses as a number, boolean, duration, or list (LOGGING_ENABLED, HTTP_TIMEOUT, ENABLED_PASSTHROUGH_PROVIDERS, …) stops startup if it holds one. JSON variables accept references inside their string values.
Provider environment variables are the exception: OPENAI_MODELS, OPENAI_MODEL_FILTER_*, and OPENAI_SESSION_STICKY_KEYS are resolved before they are parsed.
Values saved from the dashboard (provider credentials, MCP servers, guardrails) do not accept references yet.

Getting Started

Features

Pro features

MCP Proxy

Advanced

About

Secret References

Syntax

Schemes

Failures stop startup

Literal `${`

Limits

​Syntax

​Schemes

​Failures stop startup

​Literal ${

​Limits

Syntax

Schemes

Failures stop startup

Literal `${`

Limits