Skip to content

Clarify JSON vs TOML variable expansion semantics in configuration docs #4210

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lpcox merged 2 commits into from
Apr 20, 2026
Merged

Clarify JSON vs TOML variable expansion semantics in configuration docs #4210

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0af94f1
Initial plan
Copilot Apr 20, 2026
11ec5ac
docs: clarify JSON vs TOML variable expansion rules
Copilot Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/CONFIGURATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,8 @@ Run `./awmg --help` for full CLI options. Key flags:
- **`env`** (optional): Environment variables
- Set to `""` (empty string) for passthrough from host environment
- Set to `"value"` for explicit value
- Use `"${VAR_NAME}"` for environment variable expansion (fails if undefined)
- Use `"${VAR_NAME}"` for environment variable expansion (JSON stdin format only; fails if undefined)
- **TOML note**: For passthrough, use `""` (empty string) or provide explicit values; `${VAR_NAME}` syntax is not expanded in TOML server `env` values
Comment on lines 135 to +139
Copy link

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The TOML guidance here implies that setting a server env value to an empty string provides passthrough from the host env. In the TOML (file) path, [servers.<name>.env] is passed as process environment for the backend command (e.g., the docker CLI), so KEY = "" will set KEY to an empty value (overriding host), not passthrough. To pass a host env var into a Docker container from TOML, use args with -e KEY and ensure KEY is present in the gateway process environment (or set an explicit value in [servers.<name>.env]).

This issue also appears on line 361 of the same file.

See below for a potential fix:

  - Set to `"value"` for an explicit value
  - Use `"${VAR_NAME}"` for environment variable expansion (JSON stdin format only; fails if undefined)
  - **TOML note**: `${VAR_NAME}` syntax is not expanded in TOML server `env` values
  - **TOML note**: Setting a value to `""` in `[servers.<name>.env]` sets that variable to an empty string for the backend command; it does **not** passthrough the host value
  - **TOML note**: To pass a host environment variable through to a Docker container, add `-e KEY` to `args` and ensure `KEY` is present in the gateway process environment, or set an explicit value in `[servers.<name>.env]`

Copilot uses AI. Check for mistakes.

- **`url`** (required for http): HTTP endpoint URL for `type: "http"` servers

Expand Down Expand Up @@ -353,11 +354,14 @@ The `customSchemas` top-level field allows you to define custom server types bey
- **Stdio servers** must specify `container` (required)
- **HTTP servers** must specify `url` (required)
- **The `command` field is not supported** - stdio servers must use `container`
- Variable expansion with `${VAR_NAME}` is applied globally (all fields are expanded before parsing) and fails fast on undefined variables
- **TOML format**:
- Uses `command` and `args` fields directly (e.g., `command = "docker"`)
- Variable expansion with `${VAR_NAME}` is only supported in `[gateway.opentelemetry]` and legacy `[gateway.tracing]` fields
- Server `env` values, `url`, `args`, `gateway.api_key`, and other non-tracing fields are not expanded
Comment on lines +360 to +361
Copy link

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This says TOML ${VAR_NAME} expansion is supported in legacy [gateway.tracing], but the TOML loader only expands tracing variables when [gateway.opentelemetry] is present (see internal/config/config_core.go where expandTracingVariables is only called on Gateway.Opentelemetry). Either update the docs to say expansion is limited to [gateway.opentelemetry] only, or update the loader to also expand/validate variables for legacy [gateway.tracing].

Suggested change
- Variable expansion with `${VAR_NAME}` is only supported in `[gateway.opentelemetry]` and legacy `[gateway.tracing]` fields
- Server `env` values, `url`, `args`, `gateway.api_key`, and other non-tracing fields are not expanded
- Variable expansion with `${VAR_NAME}` is only supported in `[gateway.opentelemetry]` fields
- Server `env` values, `url`, `args`, `gateway.api_key`, legacy `[gateway.tracing]`, and other non-opentelemetry fields are not expanded

Copilot uses AI. Check for mistakes.
- For host environment passthrough to container `env`, use an empty string `""` value
Copy link

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After stating that TOML does not expand ${VAR_NAME} in non-tracing fields, this doc still contains other TOML-relevant examples that suggest ${VAR} works (e.g., mounts source description and the gateway.domain row). To avoid contradictory guidance, consider updating those references to be JSON-only / tracing-only (or otherwise scoping them) so the file is internally consistent.

Suggested change
- For host environment passthrough to container `env`, use an empty string `""` value
- For host environment passthrough to container `env` in TOML, use an empty string `""` value; do not use `${VAR_NAME}` in `env` because non-tracing TOML fields are not expanded

Copilot uses AI. Check for mistakes.
- **Common rules** (both formats):
- Empty/"local" type automatically normalized to "stdio"
- Variable expansion with `${VAR_NAME}` fails fast on undefined variables
- All validation errors include JSONPath and helpful suggestions
- **Mount specifications** must follow `"source:dest:mode"` format
- `source` must be an absolute path (e.g., `/host/data`)
Expand Down
Loading