# How Agent Reach Reads Configuration Values from Environment Variables

> Learn how Agent Reach reads config values from environment variables. Discover its two-step lookup system for seamless configuration management.

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

---

**Agent Reach uses a two-step lookup system where `Config.get(key)` first checks the YAML config file, then automatically falls back to an uppercase environment variable of the same name.**

The Agent Reach framework stores user settings in `~/.agent-reach/config.yaml`, but it also supports **dynamic configuration overrides via environment variables**. This hybrid approach keeps secrets out of version-controlled files while maintaining the convenience of persistent settings. According to the Agent-Reach source code, the environment variable integration is handled transparently in the configuration manager's lookup logic.

## Two-Step Configuration Lookup

The `Config` class implements a priority-based resolution system. When you call `cfg.get("some_key")`, the framework executes this sequence:

1. **YAML file lookup** – Checks `self.data` (the parsed config file contents) for the exact key
2. **Environment fallback** – If missing, calls `os.environ.get(key.upper())` to find an uppercase environment variable

This design means `openai_api_key` in your config file and `OPENAI_API_KEY` as an environment variable are treated as equivalent alternatives.

## Source Code Implementation

The environment variable reading logic lives in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) at lines 58-66. The `get` method signature accepts a key and optional default:

```python
def get(self, key: str, default: Any = None) -> Any:
    # First: check the YAML-loaded data dictionary

    if key in self.data:
        return self.data[key]
    # Second: fallback to uppercase environment variable

    env_val = os.environ.get(key.upper())
    if env_val is not None:
        return env_val
    # Finally: return the provided default (or None)

    return default

```

The key transformation (`key.upper()`) normalizes config keys to standard Unix environment variable conventions—uppercase with underscores.

## Practical Usage Examples

### Reading API Keys from Environment Variables

```python
from agent_reach.config import Config

cfg = Config()

# Preferred pattern for secrets: omit from YAML, set via environment

# export OPENAI_API_KEY="sk-abc123..."

api_key = cfg.get("openai_api_key")
print(api_key)  # → "sk-abc123..." (read from $OPENAI_API_KEY)

```

### YAML Override Takes Precedence

```python

# If config.yaml contains: openai_api_key: "sk-file-key"

# And environment has: OPENAI_API_KEY="sk-env-key"

cfg = Config()
result = cfg.get("openai_api_key")
print(result)  # → "sk-file-key" (YAML wins)

```

### Default Fallback Behavior

```python

# When neither YAML nor environment provides the value

timeout = cfg.get("request_timeout", default=30)
print(timeout)  # → 30

```

## Configuration File Path and Initialization

The `Config` class defaults to `~/.agent-reach/config.yaml`. Path handling utilities in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) support safe directory creation and resolution, ensuring the config directory exists before file operations.

| File | Purpose |
|------|---------|
| [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) | Core configuration manager with `get()` method and environment variable fallback |
| [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) | Path resolution utilities for config directory handling |

## Why This Pattern Matters for Agent Development

**Security** – API keys and database credentials never need to be written to disk.  
**Portability** – Containers and CI/CD pipelines inject configuration via environment variables.  
**Flexibility** – Developers override specific values without modifying shared config files.

The uppercase transformation convention (`openai_api_key` → `OPENAI_API_KEY`) aligns with the twelve-factor app methodology, making Agent Reach deployments predictable across cloud platforms.

## Summary

- **Primary source**: [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), lines 58-66 in the `get` method
- **Resolution order**: YAML file → uppercase environment variable → default value
- **Key transformation**: Config keys are uppercased via `key.upper()` for environment lookup
- **Default path**: `~/.agent-reach/config.yaml`
- **Best practice**: Store secrets in environment variables, general settings in YAML

## Frequently Asked Questions

### How do I override a config value with an environment variable?

Set an environment variable with the uppercase version of your config key. For `max_retries`, use `export MAX_RETRIES=5`. The `Config.get("max_retries")` call will return `5` automatically.

### What happens if a key exists in both the YAML file and the environment?

The YAML file value takes precedence. Agent Reach checks `self.data` before falling back to `os.environ`, so persistent settings override environment values.

### Can I use nested keys with environment variables?

No. The current implementation in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) only supports top-level key lookups. The `get` method receives a single string key and performs direct dictionary access and environment variable lookup without nested traversal.

### Does Agent Reach cache environment variable values?

No caching occurs. Each `Config.get()` call executes fresh lookups against both `self.data` and `os.environ`, so changes to environment variables take effect immediately at runtime.