# How Agent Reach Config System Handles Environment Variable Overrides

> Learn how Agent Reach's config system handles environment variable overrides. Discover how runtime changes securely update sensitive settings after YAML file checks.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-11

---

**The Agent Reach configuration system consults environment variables after checking the YAML config file, automatically uppercasing keys to allow runtime overrides of sensitive settings like API keys without modifying persistent storage.**

The open-source Agent Reach project (Panniantong/Agent-Reach) manages user settings through a centralized configuration class that implements a priority-based lookup system. Located at `~/.agent-reach/config.yaml`, the persistent store can be dynamically shadowed by environment variables according to the source code in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), enabling secure injection of credentials and feature flags at runtime.

## Configuration Lookup Priority

### The Three-Step Resolution Order

The `Config.get()` method defined in [[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py#L75-L84) implements a cascading lookup strategy:

1. **Configuration file** – The method first checks if the key exists in the loaded YAML data structure (`self.data`).
2. **Environment variable** – If the key is absent from the file, the function searches `os.environ` for a variable matching the uppercase version of the key (`key.upper()`).
3. **Default value** – If neither source provides the setting, the method returns the optional `default` argument or `None`.

Because the environment variable is checked **after** the file but before the default, any exported variable automatically supersedes the corresponding YAML entry.

### Uppercase Key Transformation

Environment variables follow the Unix convention of uppercase naming. When calling `config.get("groq_api_key")`, Agent Reach automatically searches for `GROQ_API_KEY` in the environment. This bridging logic between YAML snake_case keys and standard env var naming is handled transparently within the `Config` class.

## Source Code Implementation

### Core Configuration Logic

The override mechanism lives specifically in lines 75-84 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). The implementation first attempts retrieval from the in-memory dictionary representing the YAML file, then falls back to `os.environ.get(key.upper())`. This ensures that containerized deployments and CI/CD pipelines can inject secrets without touching the filesystem.

### CLI Integration

The pattern appears throughout the codebase. In [[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L694-L698), the CLI entry point uses this resolution logic to determine if required API keys are available. This allows users to deploy Agent Reach in ephemeral environments where writing sensitive data to `~/.agent-reach/config.yaml` is prohibited.

## Practical Usage Examples

### File-Based Configuration

```yaml

# ~/.agent-reach/config.yaml

groq_api_key: "file-based-key-123"
openai_api_key: "sk-file-default"

```

### Environment Override

```bash
export GROQ_API_KEY="env-override-456"
agent-reach transcribe https://example.com/audio.mp3

```

With the environment variable set, the transcribe command uses `env-override-456` despite the YAML containing a different value.

### Python API Interaction

```python
from agent_reach.config import Config

cfg = Config()

# Returns value from ~/.agent-reach/config.yaml

print(cfg.get("groq_api_key"))

# Override at runtime

import os
os.environ["GROQ_API_KEY"] = "runtime-key"
print(cfg.get("groq_api_key"))  # Returns "runtime-key"

```

### Default Fallback Handling

```python

# Returns "fallback-value" if key absent from both sources

value = cfg.get("custom_setting", default="fallback-value")

```

## Production Use Cases

### Transcription Provider Credentials

The transcription module in [[`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py#L7-L10) relies on `Config.get()` to retrieve provider-specific keys. When running in serverless environments or Docker containers, operators can inject `GROQ_API_KEY` or `OPENAI_API_KEY` without mounting persistent volumes, keeping credentials out of version control while maintaining functionality.

### Feature Detection

`Config.is_configured()` iterates through required keys using `self.get(k)` internally. This means a missing or commented-out YAML entry can be satisfied at runtime by an environment variable, supporting temporary feature toggles and A/B testing scenarios where configuration changes must not persist across sessions.

## Summary

- The `Config.get()` method implements a three-tier lookup: YAML file → environment variable → default value
- Environment variables override file settings, enabling secure runtime injection of API keys and toggles
- Keys are automatically converted to uppercase for environment lookups (e.g., `groq_api_key` becomes `GROQ_API_KEY`)
- Primary implementation resides in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) lines 75-84
- Pattern reused across CLI validation ([`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 694-698) and transcription services

## Frequently Asked Questions

### Can I use Agent Reach without a config file by setting only environment variables?

Yes. If a configuration key does not exist in `~/.agent-reach/config.yaml`, the system falls back to environment variables. As long as you provide all required settings via uppercase environment variables, the YAML file can remain empty or absent, making the tool suitable for serverless and containerized deployments.

### Why does the config system require uppercase environment variable names?

The system follows standard Unix conventions where environment variables are uppercase. The `Config.get()` method automatically transforms the requested key to uppercase via `key.upper()` before checking `os.environ`, ensuring compatibility with typical shell export practices while maintaining lowercase keys in the YAML file for readability.

### Does setting an environment variable permanently modify the config file?

No. Environment variable overrides are ephemeral and exist only for the current process lifetime. They shadow the YAML values during runtime but do not write back to `~/.agent-reach/config.yaml`, ensuring that temporary overrides for debugging or testing do not corrupt your persistent configuration.

### How do I check if a configuration value is available before using it?

Use the `Config.is_configured()` method, which internally calls `self.get(k)` for each required key. This method returns `True` only if the value exists in either the YAML file or as an environment variable override, allowing you to validate prerequisites before executing API-dependent operations.