# Agent Reach Configuration: How YAML and Environment Variable Overrides Work

> Discover how Agent Reach configuration prioritizes YAML files and uses environment variables for overrides. Learn to inject secrets securely without disk persistence.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-18

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py):

```python
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:

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.