> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel.enterpilot.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret References

> Read API keys, DSNs, and other credentials from environment variables or mounted files with ${env:...} and ${file:...} references.

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

```yaml theme={null}
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:

```bash theme={null}
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:

```yaml theme={null}
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](/docs/pro/overview).

## Failures stop startup

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

```text theme={null}
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](/docs/advanced/cli#configuration-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.