Agent Reach Configuration: How YAML and Environment Variable Overrides Work

Agent Reach checks the YAML config file first and falls back to environment variables (automatically converted to uppercase) only when a key is missing, allowing secrets to be injected without persisting them to disk.

Agent Reach is an open-source tool for automating search and retrieval tasks. Its configuration system, implemented in agent_reach/config.py, stores user-specific settings in a YAML file while supporting environment variable overrides for sensitive credentials.

Configuration Precedence in Agent Reach

The configuration loader follows a strict hierarchy. When you call Config.get(key), the method first inspects the in-memory YAML data loaded from ~/.agent-reach/config.yaml. Only if the key is absent does it query os.environ for a matching variable.

This design ensures that YAML values take precedence when explicitly set, while environment variables serve as secure fallbacks for CI pipelines or temporary overrides.

The Config.get Implementation

The precedence logic is implemented in the get method of the Config class in agent_reach/config.py:

def get(self, key: str, default: Any = None) -> Any:
    """Get a config value. Also checks environment variables (uppercase)."""
    # 1️⃣ Config file first

    if key in self.data:
        return self.data[key]

    # 2️⃣ Then env var (uppercase)

    env_val = os.environ.get(key.upper())
    if env_val:
        return env_val

    # 3️⃣ Fallback

    return default

Because os.environ is accessed dynamically on each call, changes to environment variables take effect immediately without requiring a restart.

How to Override YAML Settings with Environment Variables

To force Agent Reach to use an environment variable instead of a YAML value, you have two options:

1. Remove the key from the config file using agent-reach config delete <key>, causing the lookup to skip the YAML check and proceed to environment variables.
2. Leave the key blank (e.g., api_key: "") in the YAML file, though this returns an empty string unless you rely on the fallback behavior.

Environment variable names must match the uppercase form of the configuration key. For example, a key named exa_api_key in YAML corresponds to the environment variable EXA_API_KEY.

Practical Usage Examples

The following workflow demonstrates the interaction between the CLI-managed YAML file and environment-based overrides:

# 1️⃣ Store a long-lived secret in YAML

agent-reach config set exa_api_key "yaml-secret"

# 2️⃣ Verify YAML value is used

agent-reach search "python tutorials"

# 3️⃣ Remove the key to enable environment variable fallback

agent-reach config delete exa_api_key

# 4️⃣ Set a short-lived secret via environment variable

export EXA_API_KEY="env-secret"
agent-reach search "python tutorials"   # now uses env-secret

Store long-lived credentials in ~/.agent-reach/config.yaml and short-lived or CI-time secrets as environment variables to keep sensitive data out of version-controlled files.

Key Configuration Files

The override behavior is implemented across three core files in the Panniantong/Agent-Reach repository:

• agent_reach/config.py: Contains the Config class with the get method that implements the YAML-to-environment fallback logic.
• agent_reach/cli.py: Provides the command-line interface for config set, config delete, and other operations that modify the YAML file.
• tests/test_config.py: Validates the precedence rules, ensuring environment variables are only consulted when keys are absent from the YAML file.

Summary

• Agent Reach loads user settings from ~/.agent-reach/config.yaml and stores them in memory.
• The Config.get method prioritizes YAML values over environment variables.
• Environment variables (specified in uppercase) act as fallbacks when keys are missing from the YAML file.
• To force environment variable usage, either delete the key from the config file or leave it blank.
• Changes to environment variables take effect immediately on the next Config.get call without requiring application restarts.

Frequently Asked Questions

Can environment variables override existing YAML values in Agent Reach?

No. According to the implementation in agent_reach/config.py, the get method returns the YAML value immediately if the key exists in self.data. Environment variables only serve as fallbacks when the key is absent from the configuration file. To use an environment variable, you must first remove the key using agent-reach config delete <key>.

How are environment variable names formatted for Agent Reach configuration?

Environment variable names must be the uppercase version of the configuration key. For example, a YAML key named exa_api_key corresponds to the environment variable EXA_API_KEY. The conversion is handled automatically by the get method using key.upper() when querying os.environ.

Where is the Agent Reach configuration file stored?

The configuration file is located at ~/.agent-reach/config.yaml. This path is set in the Config class constructor in agent_reach/config.py. The CLI commands agent-reach config set and agent-reach config delete modify this file directly.

Do changes to environment variables require restarting the application?

No. Because Config.get reads from os.environ dynamically on each invocation, any changes to environment variables are reflected immediately on subsequent configuration lookups. The YAML file is only loaded once during Config initialization, but environment variables are checked fresh every time get is called.

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