How Agent Reach Reads Configuration Values from Environment Variables

Agent Reach uses a two-step lookup system where Config.get(key) first checks the YAML config file, then automatically falls back to an uppercase environment variable of the same name.

The Agent Reach framework stores user settings in ~/.agent-reach/config.yaml, but it also supports dynamic configuration overrides via environment variables. This hybrid approach keeps secrets out of version-controlled files while maintaining the convenience of persistent settings. According to the Agent-Reach source code, the environment variable integration is handled transparently in the configuration manager's lookup logic.

Two-Step Configuration Lookup

The Config class implements a priority-based resolution system. When you call cfg.get("some_key"), the framework executes this sequence:

1. YAML file lookup – Checks self.data (the parsed config file contents) for the exact key
2. Environment fallback – If missing, calls os.environ.get(key.upper()) to find an uppercase environment variable

This design means openai_api_key in your config file and OPENAI_API_KEY as an environment variable are treated as equivalent alternatives.

Source Code Implementation

The environment variable reading logic lives in agent_reach/config.py at lines 58-66. The get method signature accepts a key and optional default:

def get(self, key: str, default: Any = None) -> Any:
    # First: check the YAML-loaded data dictionary

    if key in self.data:
        return self.data[key]
    # Second: fallback to uppercase environment variable

    env_val = os.environ.get(key.upper())
    if env_val is not None:
        return env_val
    # Finally: return the provided default (or None)

    return default

The key transformation (key.upper()) normalizes config keys to standard Unix environment variable conventions—uppercase with underscores.

Practical Usage Examples

Reading API Keys from Environment Variables

from agent_reach.config import Config

cfg = Config()

# Preferred pattern for secrets: omit from YAML, set via environment

# export OPENAI_API_KEY="sk-abc123..."

api_key = cfg.get("openai_api_key")
print(api_key)  # → "sk-abc123..." (read from $OPENAI_API_KEY)

YAML Override Takes Precedence

# If config.yaml contains: openai_api_key: "sk-file-key"

# And environment has: OPENAI_API_KEY="sk-env-key"

cfg = Config()
result = cfg.get("openai_api_key")
print(result)  # → "sk-file-key" (YAML wins)

Default Fallback Behavior

# When neither YAML nor environment provides the value

timeout = cfg.get("request_timeout", default=30)
print(timeout)  # → 30

Configuration File Path and Initialization

The Config class defaults to ~/.agent-reach/config.yaml. Path handling utilities in agent_reach/utils/paths.py support safe directory creation and resolution, ensuring the config directory exists before file operations.

File	Purpose
agent_reach/config.py	Core configuration manager with get() method and environment variable fallback
agent_reach/utils/paths.py	Path resolution utilities for config directory handling

Why This Pattern Matters for Agent Development

Security – API keys and database credentials never need to be written to disk.
Portability – Containers and CI/CD pipelines inject configuration via environment variables.
Flexibility – Developers override specific values without modifying shared config files.

The uppercase transformation convention (openai_api_key → OPENAI_API_KEY) aligns with the twelve-factor app methodology, making Agent Reach deployments predictable across cloud platforms.

Summary

• Primary source: agent_reach/config.py, lines 58-66 in the get method
• Resolution order: YAML file → uppercase environment variable → default value
• Key transformation: Config keys are uppercased via key.upper() for environment lookup
• Default path: ~/.agent-reach/config.yaml
• Best practice: Store secrets in environment variables, general settings in YAML

Frequently Asked Questions

How do I override a config value with an environment variable?

Set an environment variable with the uppercase version of your config key. For max_retries, use export MAX_RETRIES=5. The Config.get("max_retries") call will return 5 automatically.

What happens if a key exists in both the YAML file and the environment?

The YAML file value takes precedence. Agent Reach checks self.data before falling back to os.environ, so persistent settings override environment values.

Can I use nested keys with environment variables?

No. The current implementation in agent_reach/config.py only supports top-level key lookups. The get method receives a single string key and performs direct dictionary access and environment variable lookup without nested traversal.

Does Agent Reach cache environment variable values?

No caching occurs. Each Config.get() call executes fresh lookups against both self.data and os.environ, so changes to environment variables take effect immediately at runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}