How Environment Variables Override YAML Settings in Agent Reach Configuration

Environment variables act as fallback values that override YAML settings in Agent Reach only when the configuration key is absent from the file, following a strict precedence where in-file definitions take priority over uppercase environment variables.

Agent Reach stores user-specific configuration in ~/.agent-reach/config.yaml and uses the Config class to resolve settings at runtime. Understanding how environment variables override YAML settings in Agent Reach configuration allows developers to securely inject secrets without persisting them to disk while maintaining default values in version-controlled files. The resolution logic implemented in agent_reach/config.py prioritizes YAML entries but seamlessly falls back to environment variables when keys are missing or explicitly cleared.

Configuration Precedence in Agent Reach

The Config class implements a three-tier lookup system that determines whether a value comes from the YAML file, an environment variable, or a default parameter. When you call Config.get(key), the method evaluates sources in strict order:

1. YAML file values – Checked first via self.data[key]
2. Environment variables – Checked second via os.environ.get(key.upper())
3. Default fallback – Returned only if neither source provides a value

This hierarchy means that YAML settings always win when a key exists in the configuration file, even if an environment variable with the same name is set. Environment variables only serve as fallback mechanisms or injection points for secrets that should not be written to the persistent configuration file.

The Config.get Implementation

The precedence logic lives in the get method of the Config class within 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 the method checks self.data before querying os.environ, any value defined in ~/.agent-reach/config.yaml masks corresponding environment variables. The environment variable name must match the uppercase form of the configuration key (e.g., exa_api_key in YAML matches EXA_API_KEY in the environment).

How to Force Environment Variables to Override YAML

To make environment variables override existing YAML settings, you must ensure the key is absent from the in-memory configuration data. You have two approaches to achieve this:

Remove the key entirely from the configuration file using the CLI:

agent-reach config delete exa_api_key

Leave the key blank in the YAML file:

exa_api_key: ""

Once the key is empty or deleted from the YAML file, Config.get will skip the first branch of the conditional and proceed to check os.environ, effectively allowing the environment variable to supply the value. Because os.environ is accessed fresh on every get call, changes to environment variables take effect immediately without restarting the application.

Practical Configuration Workflow

Here is a complete workflow demonstrating how to switch between YAML-persisted secrets and environment-injected values:

# 1️⃣ Store a key in YAML (persisted to ~/.agent-reach/config.yaml)

agent-reach config set exa_api_key "yaml-secret"

# 2️⃣ Verify YAML takes precedence

agent-reach search "python tutorials"   # Uses "yaml-secret"

# 3️⃣ Export an environment variable (ignored while YAML key exists)

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

# 4️⃣ Remove the YAML key to enable environment variable fallback

agent-reach config delete exa_api_key
agent-reach search "python tutorials"   # Now uses "env-secret"

This pattern allows you to commit a template configuration file to version control while keeping production secrets in environment variables that override the base settings at runtime.

Key Source Files

The configuration resolution system spans three critical 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 manipulate the YAML file
• tests/test_config.py – Validates the precedence behavior, ensuring that file-based configuration correctly masks environment variables when present

Summary

• YAML precedence: Values in ~/.agent-reach/config.yaml always take priority over environment variables when the key exists in the file.
• Environment fallback: Uppercase environment variables (e.g., EXA_API_KEY) provide values only when the corresponding key is missing from YAML or explicitly deleted.
• Runtime updates: Because Config.get queries os.environ on every call, environment variable changes apply immediately without reloading the configuration object.
• Security pattern: Store long-lived development secrets in YAML and short-lived or CI-specific credentials as environment variables to keep sensitive data out of version control.

Frequently Asked Questions

How do I completely override a YAML value with an environment variable in Agent Reach?

To completely override a YAML value, you must first delete the key from the configuration file using agent-reach config delete <key> or leave it blank in ~/.agent-reach/config.yaml. Once the key is absent from the YAML data, Config.get will fall back to checking the uppercase environment variable, allowing it to provide the effective value.

Why is my environment variable not overriding the YAML setting?

Environment variables only serve as fallback values in Agent Reach. If the key exists in ~/.agent-reach/config.yaml with any non-empty value, the Config.get method returns the YAML value immediately and never checks os.environ. The library intentionally prioritizes file-based configuration to ensure explicit user settings persist across sessions.

What naming convention should I use for environment variables?

Agent Reach converts configuration keys to uppercase when checking environment variables. For a YAML key like exa_api_key, set an environment variable named EXA_API_KEY. The Config.get method calls key.upper() internally, so you must use the capitalized form for the fallback mechanism to recognize your variable.

Can I change environment variables without restarting my Agent Reach application?

Yes. Because the get method in agent_reach/config.py queries os.environ fresh on every invocation, changes to environment variables take effect immediately on the next configuration lookup. There is no need to reload the Config object or restart the process, making this approach suitable for dynamic secret rotation in long-running applications.

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