# Agent Reach Config Class Environment Variable Overrides: Secure YAML Configuration Management

> Learn how Agent Reach's Config class uses environment variable overrides to securely manage YAML configurations without editing files for temporary changes.

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

---

**Agent Reach's `Config` class implements a fallback mechanism where environment variables automatically override missing or unset YAML configuration values, enabling secure, temporary configuration changes without editing files.**

The Panniantong/Agent-Reach repository provides a robust configuration management system through its `Config` class, which balances persistent file storage with flexible runtime overrides. By storing settings in `~/.agent-reach/config.yaml` while supporting **Agent Reach config class environment variable overrides**, the system keeps credentials out of source control and supports dynamic configuration for CI/CD pipelines and local development.

## How the Config Class Loads and Resolves Values

When instantiated, the `Config` class loads the YAML configuration file into an internal dictionary called `self.data` (lines 41-47 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)). This initialization occurs automatically, ensuring that persistent settings are available immediately after creating a `Config` instance.

The `get()` method implements a two-tier lookup strategy defined in lines 70-78. First, it queries the internal `self.data` dictionary for the requested key. If the key is absent, the method searches for an environment variable with the same name converted to **uppercase**. This design ensures that file-based configurations take precedence, while environment variables serve as secure fallbacks for missing or intentionally removed keys.

## Environment Variable Naming Convention

Environment variables must match the configuration key name exactly but in uppercase format. For example, the configuration key `exa_api_key` corresponds to the environment variable `EXA_API_KEY`. This pattern applies to all feature-specific keys listed in `FEATURE_REQUIREMENTS` (lines 22-28 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)), including API keys for GitHub, Exa, and other integrated platforms.

Because the lookup is case-sensitive, exporting `exa_api_key` (lowercase) will not work; you must use `EXA_API_KEY` (uppercase) for the fallback mechanism to recognize the value.

## Write-Through Persistence Operations

The `set()` and `delete()` methods provide immediate **write-through** functionality to the YAML file. When you call `set(key, value)`, the method updates `self.data` and immediately invokes `save()` to persist changes to disk (lines 80-88). Similarly, `delete()` removes the key from the dictionary and saves the file, ensuring that subsequent `get()` calls will fall back to environment variables if the key no longer exists in the configuration file.

This atomic update pattern prevents data loss and ensures that the YAML file always reflects the current in-memory state.

## Integration Across the Agent Reach Codebase

The configuration system integrates with several core components:

- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)** – Queries `Config.is_configured()` to determine whether required API credentials are available before initiating platform operations.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Serves as the command-line entry point, using `Config` to read and write user settings interactively.
- **[`tests/test_config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_config.py)** – Contains unit tests that verify the environment-variable fallback behavior and YAML persistence logic.

These components demonstrate how `Agent Reach config class environment variable overrides` enable flexible deployment scenarios, from local development with file-based configs to production environments using injected secrets.

## Practical Implementation Examples

The following examples demonstrate how to initialize the configuration, retrieve values with fallback support, persist new settings, and delete keys while relying on environment variables.

```python
from agent_reach.config import Config

# Initialise – loads ~/.agent-reach/config.yaml if present

cfg = Config()

# ------------------------------------------------------------------

# 1️⃣ Retrieve a value that may be stored in the YAML file

# ------------------------------------------------------------------

api_key = cfg.get("exa_api_key")
print("EXA API key from config file:", api_key)

# ------------------------------------------------------------------

# 2️⃣ Override via environment variable (no need to edit the file)

# ------------------------------------------------------------------

# In the shell: export EXA_API_KEY="temp‑override"

# Then the same call picks up the env var:

api_key = cfg.get("exa_api_key")
print("EXA API key from env var:", api_key)

# ------------------------------------------------------------------

# 3️⃣ Persist a new value to the YAML file

# ------------------------------------------------------------------

cfg.set("github_token", "ghp_XXXXXXXXXXXXXXXXXXXX")
print("Saved GitHub token:", cfg.get("github_token"))

# ------------------------------------------------------------------

# 4️⃣ Delete a key (removes it from the file)

# ------------------------------------------------------------------

cfg.delete("github_token")
print("After delete, env fallback only:", cfg.get("github_token"))

```

## Summary

- The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages settings in `~/.agent-reach/config.yaml` with environment variable fallback support.
- The `get()` method checks the YAML file first (lines 70-78), then searches for uppercase environment variables if keys are missing.
- The `set()` and `delete()` methods provide immediate persistence to the YAML file via write-through operations (lines 80-88).
- **Agent Reach config class environment variable overrides** enable secure credential management and temporary configuration changes without file modification.

## Frequently Asked Questions

### How do I override a specific Agent Reach configuration value using environment variables?

Export an environment variable with the same name as the configuration key in uppercase. For example, to override `exa_api_key`, run `export EXA_API_KEY="your-key"` in your shell before running Agent Reach. When the code calls `config.get("exa_api_key")`, it will retrieve the value from the environment if the key is absent from the YAML file.

### Does the Config class prefer environment variables over the YAML file?

No, the `get()` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) checks the YAML file first. Environment variables only serve as fallback values when a key is absent from `~/.agent-reach/config.yaml` or has been deleted. This precedence ensures that explicit file settings remain authoritative unless intentionally cleared.

### Where does Agent Reach store its persistent configuration?

Persistent settings are stored in `~/.agent-reach/config.yaml`. The `Config` class loads this file into memory during initialization (lines 41-47) and writes changes back to disk when `set()` or `delete()` is called. If the file does not exist, the class operates with an empty configuration, relying entirely on environment variable fallbacks.

### Can I use environment variables for all Agent Reach configuration options?

Yes, any key defined in `FEATURE_REQUIREMENTS` (lines 22-28 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) supports environment variable fallback, allowing you to externalize sensitive credentials like API keys and tokens. The uppercase conversion rule applies universally to all configuration keys managed by the `Config` class.