Skip to content

Fix environment variable documentation discrepancies #901

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
Feb 11, 2026
Merged

Fix environment variable documentation discrepancies #901

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
464cde3
Initial plan
Claude Feb 11, 2026
2763444
Fix environment variables documentation discrepancies
Claude Feb 11, 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
3 changes: 2 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -366,12 +366,13 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml

- `GITHUB_PERSONAL_ACCESS_TOKEN` - GitHub auth
- `DOCKER_API_VERSION` - 1.43 (arm64) or 1.44 (amd64)
- `PORT`, `HOST`, `MODE` - Server config (via run.sh)
- `DEBUG` - Enable debug logging (e.g., `DEBUG=*`, `DEBUG=server:*,launcher:*`)
- `DEBUG_COLORS` - Control colored output (0 to disable, auto-disabled when piping)
- `MCP_GATEWAY_LOG_DIR` - Log file directory (sets default for `--log-dir` flag, default: `/tmp/gh-aw/mcp-logs`)
- `MCP_GATEWAY_PAYLOAD_DIR` - Large payload storage directory (sets default for `--payload-dir` flag, default: `/tmp/jq-payloads`)

**Note:** The `PORT`, `HOST`, and `MODE` environment variables are used only by test scripts and are not read by the gateway application. The gateway uses command-line flags instead: `--listen` for bind address and `--routed`/`--unified` for mode selection.
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

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

This note claims PORT, HOST, and MODE are used only by test scripts, but run.sh also reads all three and uses them to construct the ./awmg invocation (--listen ${HOST}:${PORT} and $MODE). The note should be revised to reflect that these vars are script-level inputs (used by run.sh and some test helpers), not strictly test-only.

Suggested change
**Note:** The `PORT`, `HOST`, and `MODE` environment variables are used only by test scripts and are not read by the gateway application. The gateway uses command-line flags instead: `--listen` for bind address and `--routed`/`--unified` for mode selection.
**Note:** The `PORT`, `HOST`, and `MODE` environment variables are consumed by the `run.sh` wrapper and some test helper scripts to construct the `./awmg` invocation (for example, `--listen ${HOST}:${PORT}` and the selected mode), but they are not read directly by the gateway binary. The gateway itself uses command-line flags instead: `--listen` for bind address and `--routed`/`--unified` for mode selection.

Copilot uses AI. Check for mistakes.

**File Logging:**
- Operational logs are always written to log files in the configured log directory
- Default log directory: `/tmp/gh-aw/mcp-logs` (configurable via `--log-dir` flag or `MCP_GATEWAY_LOG_DIR` env var)
Expand Down
8 changes: 5 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,18 +312,20 @@ When running locally (`run.sh`), these variables are optional (warnings shown if
| `MCP_GATEWAY_PORT` | Gateway listening port | `8000` |
| `MCP_GATEWAY_DOMAIN` | Gateway domain | `localhost` |
| `MCP_GATEWAY_API_KEY` | API authentication key | (disabled) |
| `HOST` | Gateway bind address | `0.0.0.0` |
| `MODE` | Gateway mode flag | `--routed` |
| `MCP_GATEWAY_LOG_DIR` | Log file directory (sets default for `--log-dir` flag) | `/tmp/gh-aw/mcp-logs` |
| `MCP_GATEWAY_PAYLOAD_DIR` | Large payload storage directory (sets default for `--payload-dir` flag) | `/tmp/jq-payloads` |
| `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` | Size threshold in bytes for payload storage (sets default for `--payload-size-threshold` flag) | `10240` |
| `DEBUG` | Enable debug logging with pattern matching (e.g., `*`, `server:*,launcher:*`) | (disabled) |
| `DEBUG_COLORS` | Control colored debug output (0 to disable, auto-disabled when piping) | Auto-detect |

**Note:** The `HOST` and `MODE` environment variables are not used by the gateway application. Use the `--listen` flag to set the bind address (default: `127.0.0.1:3000`) and the `--routed` or `--unified` flags to set the gateway mode.
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

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

The note states HOST and MODE are not used and instructs users to use --listen/--routed/--unified. While the Go binary doesn’t read HOST/MODE, run.sh does read HOST, PORT, and MODE and converts them into those flags (FLAGS="$MODE --listen ${HOST}:${PORT}"). In this “running locally (run.sh)” section, the current wording is misleading because run.sh doesn’t forward arbitrary CLI args, so users can’t actually supply --listen/--routed/--unified unless they bypass run.sh and run ./awmg directly. Consider documenting HOST/MODE as run.sh-only inputs (or clarify the note to distinguish run.sh vs awmg).

Suggested change
**Note:** The `HOST` and `MODE` environment variables are not used by the gateway application. Use the `--listen` flag to set the bind address (default: `127.0.0.1:3000`) and the `--routed` or `--unified` flags to set the gateway mode.
**Note:** When using `run.sh`, the script reads the `HOST`, `PORT`, and `MODE` environment variables and translates them into the equivalent `--listen` and `--routed`/`--unified` flags for the gateway binary. The gateway application itself does not read `HOST` or `MODE` directly. If you invoke `./awmg` manually (without `run.sh`), use the `--listen` flag to set the bind address (default: `127.0.0.1:3000`) and the `--routed` or `--unified` flags to select the gateway mode.

Copilot uses AI. Check for mistakes.

### Docker Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `DOCKER_HOST` | Docker daemon socket path | `/var/run/docker.sock` |
| `DOCKER_API_VERSION` | Docker API version | Auto-detected (1.43 for arm64, 1.44 for amd64) |
| `DOCKER_API_VERSION` | Docker API version (set by helper scripts, Docker client auto-negotiates) | Set by run.sh based on architecture |
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

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

The updated DOCKER_API_VERSION default/description doesn’t match what the helper scripts actually do: run.sh/run_containerized.sh first try to set DOCKER_API_VERSION from docker version --format '{{.Server.APIVersion}}' and only fall back to an architecture-based value. The table currently says “Set by run.sh based on architecture”, which omits the primary (server API) behavior and may be inaccurate if the server API differs. Please align the wording/default with the scripts’ logic (server API version when available; architecture fallback).

Suggested change
| `DOCKER_API_VERSION` | Docker API version (set by helper scripts, Docker client auto-negotiates) | Set by run.sh based on architecture |
| `DOCKER_API_VERSION` | Docker API version (set by helper scripts: uses `docker version --format '{{.Server.APIVersion}}'` when available, with an architecture-based fallback) | Server API version when available; architecture-based fallback |

Copilot uses AI. Check for mistakes.

## Containerized Mode

Expand Down