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

Agent Reach automatically falls back to environment variables for any configuration key missing from 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, 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 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.

• 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 file.

Shell Configuration on Linux and macOS

Set variables in your terminal before running commands:

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:

$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:

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:

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) 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
• 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}