# How to Use Environment Variables for Agent Reach Configuration Instead of config.yaml

> Learn how to configure Agent Reach using environment variables instead of config.yaml. Agent Reach automatically falls back to your environment variables for a seamless setup.

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

---

**Agent Reach automatically falls back to environment variables for any configuration key missing from [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) by converting the key to uppercase and checking `os.environ`, allowing you to run the tool without any YAML file.**

Agent Reach stores user settings in `~/.agent-reach/config.yaml` by default, but the codebase is designed to prioritize environment variables when available. This hybrid approach lets you configure sensitive credentials and feature flags entirely through shell exports, making it ideal for CI/CD pipelines and containerized deployments. Understanding how the `Config` class resolves variables will help you secure your setup without touching the filesystem.

## How Environment Variable Fallback Works in Agent Reach

The configuration system is implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), where the `Config` class manages both YAML file loading and environment variable resolution.

When you request a value using `Config.get(key)`, the method follows a strict precedence order. First, it checks the loaded YAML data from `~/.agent-reach/config.yaml`. If the key is absent, it automatically transforms the key to uppercase and queries `os.environ.get(key.upper())`.

This means a key like `groq_api_key` in your YAML file becomes `GROQ_API_KEY` in your environment, and the CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and all channel implementations in `agent_reach/channels/*.py` use this same `Config` instance to ensure consistent behavior across the entire application.

## Common Environment Variables for Agent Reach Features

Each feature maps its YAML configuration keys to uppercase environment variables following the convention established in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

- **EXA Search**: Set `EXA_API_KEY` instead of `exa_api_key` in YAML
- **Twitter/X Reach**: Use `TWITTER_AUTH_TOKEN` and `TWITTER_CT0` for `twitter_auth_token` and `twitter_ct0`
- **Groq Whisper**: Export `GROQ_API_KEY` to replace `groq_api_key`
- **OpenAI Whisper**: Use `OPENAI_API_KEY` for `openai_api_key`
- **GitHub Integration**: Set `GITHUB_TOKEN` for `github_token`

## Practical Implementation Examples

You can run Agent Reach entirely through environment variables without creating a [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file.

### Shell Configuration on Linux and macOS

Set variables in your terminal before running commands:

```bash
export EXA_API_KEY="your-exa-key"
export GROQ_API_KEY="your-groq-key"
export GITHUB_TOKEN="your-github-token"

# Verify configuration works

python -m agent_reach.cli doctor

```

### Windows PowerShell Configuration

For Windows environments, use the `$env:` syntax:

```powershell
$env:EXA_API_KEY = "your-exa-key"
$env:GROQ_API_KEY = "your-groq-key"
$env:GITHUB_TOKEN = "your-github-token"

python -m agent_reach.cli doctor

```

### Direct Python API Usage

When importing Agent Reach as a library, the `Config` class reads environment variables automatically:

```python
from agent_reach.config import Config

cfg = Config()
groq_key = cfg.get("groq_api_key")      # Reads GROQ_API_KEY env var

github_token = cfg.get("github_token")    # Reads GITHUB_TOKEN env var

print(f"Groq key: {groq_key}, GitHub token: {github_token}")

```

### Running Channels with Environment-Based Credentials

For feature-specific authentication like Twitter searches:

```bash
export TWITTER_AUTH_TOKEN="your-auth-token"
export TWITTER_CT0="your-ct0-token"

python -m agent_reach.cli search "OpenAI" --channel twitter

```

## Key Source Files and Implementation Details

Understanding the source code helps troubleshoot configuration issues.

**agent_reach/config.py**
This file defines `Config.CONFIG_DIR` and `Config.CONFIG_FILE` for the default YAML location. The `Config.get` method implements the fallback logic, checking `os.environ.get(key.upper())` when YAML values are missing.

**agent_reach/cli.py**
The CLI entry point instantiates a global `Config` object and relies on environment variables for feature detection and credential validation around lines 672-673.

**agent_reach/channels/*.py**
Each channel implementation (such as [`twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py)) queries `Config.get` for authentication tokens, making them environment-variable compatible by default.

**tests/test_config.py**
The test suite verifies that environment variables take precedence and are correctly parsed, ensuring reliable behavior across updates.

## Summary

- Agent Reach checks environment variables automatically when keys are missing from [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml)
- Environment variable names are the uppercase version of configuration keys (e.g., `groq_api_key` becomes `GROQ_API_KEY`)
- The `Config.get` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles this resolution transparently
- All channels and CLI commands inherit this behavior, supporting fully env-based configuration
- This approach eliminates the need to store secrets on disk, improving security for production deployments

## Frequently Asked Questions

### Do I need to create an empty config.yaml file if using only environment variables?

No. If all required configuration keys are present as environment variables, Agent Reach will function without any [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file existing. The `Config` class only attempts to load the YAML file for defaults but does not require it when environment variables provide the necessary values.

### What happens if both config.yaml and environment variables define the same key?

The YAML file takes precedence for explicitly defined keys. However, if a key is missing from YAML or the file does not exist, the system falls back to the environment variable. To force environment variable usage, either remove the key from your YAML file or delete the configuration file entirely.

### Are environment variable names case-sensitive?

Yes. The `Config.get` method specifically looks for the uppercase version of the key using `key.upper()`, so `groq_api_key` in code expects `GROQ_API_KEY` in your environment. Lowercase or mixed-case variations will not be recognized.

### Which Agent Reach features support environment variable configuration?

All features using the standard `Config` class support this mechanism, including Exa Search, Twitter/X Reach, Groq Whisper, OpenAI Whisper, and GitHub integration. Any third-party API keys or tokens requested through `cfg.get()` in the codebase automatically support environment variable fallback according to the source implementation.