📚 Environment Variables Documentation Discrepancies - HOST and MODE

[github-actions]

Summary

Found 2 environment variables documented in README.md that are not actually used in production code, and 2 functional environment variables that are undocumented.

• Workflow Run: §21904121957
• Date: 2026-02-11
• Branch: main

Important Issues 🟡

1. HOST Environment Variable - Documented But Not Used

Location: README.md, line 315

Problem: The HOST variable is documented as "Gateway bind address" with default 0.0.0.0, but this variable is NOT used anywhere in the production Go code.

Actual Behavior:

• Only appears in test file: test/integration/pipe_launch_test.go
• The actual bind address is controlled by the --listen flag (default: 127.0.0.1:3000)
• run.sh script sets HOST but the Go application ignores it

Impact: Users may set HOST expecting it to work, but it has no effect. This could cause confusion when trying to bind to different addresses.

Suggested Fix:

### Optional (Non-Containerized Mode)

When running locally (`run.sh`), these variables are optional (warnings shown if missing):

| Variable | Description | Default |
|----------|-------------|---------|
| `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` |
+ | **Note:** Use `--listen` flag to set bind address (default: `127.0.0.1:3000`) |
| `MODE` | Gateway mode flag | `--routed` |

Code Reference: internal/cmd/flags_core.go defines --listen flag but no HOST environment variable handling

---

2. MODE Environment Variable - Documented But Not Used

Location: README.md, line 316

Problem: The MODE variable is documented as "Gateway mode flag" with default --routed, but this variable is NOT used in the production Go code.

Actual Behavior:

• Only appears in test file: test/integration/pipe_launch_test.go
• The actual mode is controlled by the --routed or --unified flags
• run.sh script sets MODE but the Go application ignores it

Impact: Users may set MODE expecting to switch between routed/unified modes, but it has no effect. Must use command-line flags instead.

Suggested Fix:

- | `MODE` | Gateway mode flag | `--routed` |
+ | **Note:** Use `--routed` or `--unified` flags to set gateway mode |

Code Reference: internal/cmd/flags_core.go defines --routed and --unified flags but no MODE environment variable handling

---

3. DEBUG Environment Variable - Functional But Undocumented

Location: Not documented in README.md Environment Variables section (lines 292-326)

Problem: The DEBUG environment variable is fully functional and controls debug logging, but it's only documented in the "Logging" section (line 481), not in the comprehensive environment variables table.

Actual Behavior:

• Enables debug logging with pattern matching (e.g., DEBUG=*, DEBUG=server:*,launcher:*)
• Implemented in internal/logger/logger.go:46
• Widely used throughout the codebase

Impact: Users may miss this important debugging feature when reviewing the environment variables section.

Suggested Fix: Add to environment variables table:

| Variable | Description | Default |
|----------|-------------|---------|
+ | `DEBUG` | Enable debug logging with pattern matching (e.g., `*`, `server:*`) | (disabled) |
+ | `DEBUG_COLORS` | Control colored debug output (0 to disable) | Auto-detect |

Code Reference: internal/logger/logger.go:26,46

---

4. DEBUG_COLORS Environment Variable - Functional But Undocumented

Location: Not documented in README.md Environment Variables section

Problem: The DEBUG_COLORS environment variable controls colored output for debug logs but is not documented.

Actual Behavior:

• Controls whether debug logs use ANSI color codes
• Auto-disabled when piping output
• Implemented in internal/logger/logger.go:26

Impact: Users may want to disable colors in specific scenarios but don't know this option exists.

Suggested Fix: Add to environment variables table (see suggestion above)

Code Reference: internal/logger/logger.go:26

---

Minor Issues 🔵

5. DOCKER_API_VERSION - Set But Not Read

Location: README.md, line 326

Problem: Documentation states "Auto-detected (1.43 for arm64, 1.44 for amd64)", but the Go code doesn't actually read this environment variable. It's set by run.sh and run_containerized.sh but never used.

Actual Behavior:

• Shell scripts set it based on architecture
• Go code doesn't reference this variable
• Docker client auto-negotiates API version

Impact: Low - Docker client handles version negotiation automatically. The documentation is misleading but the functionality works.

Suggested Fix:

- | `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, not used by Go code) | Set by run.sh based on architecture |

Code Reference: Search results show no usage in Go code; only in shell scripts

---

Accurate Sections ✅

• Configuration Modes (TOML/JSON) - verified accurate
• Variable Expansion (${VAR_NAME}) - verified accurate
• Schema Normalization - verified accurate
• Routing Modes (routed/unified) - verified accurate
• Docker Support - verified accurate
• HTTP Transport support - verified accurate
• Container Detection - verified accurate
• Per-ServerID Logs - verified accurate
• Payload size threshold defaults (10240 bytes) - verified accurate
• All gateway configuration fields - verified accurate
• All server configuration fields - verified accurate
• Validation rules - verified accurate

Tested Commands

All commands from CONTRIBUTING.md were validated against Makefile:

• ✅ make build - target exists (line 14)
• ✅ make test - target exists (line 52)
• ✅ make test-unit - target exists (line 40)
• ✅ make test-integration - target exists (line 55)
• ✅ make test-all - target exists (line 46)
• ✅ make lint - target exists (line 21)
• ✅ make coverage - target exists (line 78)
• ✅ make format - target exists (line 118)
• ✅ make clean - target exists (line 124)
• ✅ make install - target exists (line 207)
• ✅ Go version requirement (1.25.0) matches go.mod
• ✅ Binary name awmg is consistent throughout

Recommendations

Immediate Actions Required:

1. Remove or clarify HOST variable - Either document that --listen flag should be used, or implement HOST env var support
2. Remove or clarify MODE variable - Either document that flags should be used, or implement MODE env var support
3. Add DEBUG and DEBUG_COLORS to env vars table - These are functional and should be documented in the comprehensive table

Nice to Have:

1. Clarify DOCKER_API_VERSION usage - Note that it's set by scripts but not used by Go code (Docker auto-negotiates)

Code References

• Environment variable validation: internal/config/validation_env.go
• Logger environment variables: internal/logger/logger.go
• Command-line flags: internal/cmd/flags_core.go, internal/cmd/flags_logging.go
• Test-only usage: test/integration/pipe_launch_test.go

AI generated by Nightly Documentation Reconciler

• expires on Feb 14, 2026, 12:05 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster