# Agent Reach Environment Variables: Complete Runtime Configuration Guide

> Discover Agent Reach environment variables for runtime configuration. Learn how to override YAML settings and authenticate channels like Twitter and XHS. Your complete guide.

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

---

**Agent Reach utilizes environment variables prefixed with `AGENT_REACH_` to override YAML configuration values, relies on `HOME` for config file resolution, and requires platform-specific variables like `TWITTER_COOKIE`, `XHS_COOKIE`, `REDDIT_COOKIE`, `XIAOYUZHOU_COOKIE`, and `EXA_API_KEY` for channel authentication.**

Agent Reach is an open-source Python framework for automating tasks across social media and search platforms. The application reads **environment variables** at runtime to manage configuration overrides and authenticate with external services, making proper environment setup critical for secure deployments.

## Configuration Override Pattern (AGENT_REACH_*)

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `Config` class implements a dynamic override system that applies environment variables on top of YAML file settings.

### How Config Overrides Work

When `Config.load()` executes, it scans all environment variables for entries starting with `AGENT_REACH_`. The method extracts these values and injects them into the configuration dictionary using dot-notation key mapping.

```python
import os
from agent_reach.config import Config

# Set environment variable before initialization

os.environ["AGENT_REACH_OPENAI_API_KEY"] = "sk-abc123"
os.environ["AGENT_REACH_DEBUG_MODE"] = "true"

config = Config()
api_key = config.get("openai.api_key")  # Returns "sk-abc123"

debug = config.get("debug_mode")        # Returns "true"

```

### Transformation Convention

The configuration loader transforms environment variable names using a specific pattern. In lines 51-57 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the code strips the `AGENT_REACH_` prefix, converts the remaining string to lowercase, and replaces underscores with dots to create nested keys.

| Environment Variable | Config Key Access |
|---------------------|------------------|
| `AGENT_REACH_OPENAI_API_KEY` | `config.get("openai.api_key")` |
| `AGENT_REACH_LOG_LEVEL` | `config.get("log.level")` |
| `AGENT_REACH_TWITTER_TIMEOUT` | `config.get("twitter.timeout")` |

## Core System Variables

### HOME Directory Resolution

Agent Reach requires the `HOME` environment variable to locate the default configuration file. In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `_default_config_path()` method uses `os.getenv("HOME", ".")` to construct the path `$HOME/.agent_reach/config.yaml`.

The `Probe` class in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) explicitly verifies that `HOME` exists in `os.environ` as part of its diagnostic checks, returning `"home_set": True` only when the variable is present.

## Platform Authentication Variables

Channel implementations in the `agent_reach/channels/` directory rely on specific environment variables for authentication, primarily using cookie-based authentication for social media platforms.

### Social Media Channel Cookies

Each social platform channel expects its authentication token via a dedicated cookie variable:

- **`TWITTER_COOKIE`**: Required by `TwitterChannel` in [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) (line 20). The constructor checks `os.getenv("TWITTER_COOKIE")` and updates session headers when present.

- **`XHS_COOKIE`**: Required by `XiaohongshuChannel` in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (line 16). The channel logs a warning if this variable is unset, indicating limited functionality.

- **`REDDIT_COOKIE`**: Used by `RedditChannel` in [`agent_reach/channels/reddit.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/reddit.py) (line 15). The cookie is optional but enables authenticated API requests when provided.

- **`XIAOYUZHOU_COOKIE`**: Required by `XiaoyuzhouChannel` in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) (line 15) for Little Universe platform access.

### Search API Keys

- **`EXA_API_KEY`**: Mandatory for `ExaSearchChannel` in [`agent_reach/channels/exa_search.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/exa_search.py). The constructor raises a `ValueError` if `os.getenv("EXA_API_KEY")` returns `None`, preventing initialization without credentials.

## External Service Integration

The repository includes an `.env.example` file documenting additional variables that may be required by underlying SDKs, even though Agent Reach does not access them directly in the analyzed source:

- **`OPENAI_API_KEY`**: Used by OpenAI SDK integration for LLM features
- **`ELEVENLABS_API_KEY`**: Used by ElevenLabs SDK for text-to-speech functionality

These variables follow standard naming conventions expected by their respective third-party libraries rather than the `AGENT_REACH_` prefix pattern.

## Summary

- **Agent Reach environment variables** use the `AGENT_REACH_` prefix to override any configuration value in the YAML file, converting uppercase underscores to lowercase dots (e.g., `AGENT_REACH_FOO_BAR` becomes `foo.bar`).
- The **`HOME`** variable is required for determining the default configuration directory at `~/.agent_reach/`.
- **Platform-specific cookies** (`TWITTER_COOKIE`, `XHS_COOKIE`, `REDDIT_COOKIE`, `XIAOYUZHOU_COOKIE`) enable authenticated access to social media channels without OAuth flows.
- **`EXA_API_KEY`** is mandatory for the Exa Search channel and will raise an exception if missing.
- Standard API keys (`OPENAI_API_KEY`, `ELEVENLABS_API_KEY`) are handled by underlying SDKs rather than Agent Reach's configuration system directly.

## Frequently Asked Questions

### How do I override a nested configuration value using environment variables?

Prefix the variable with `AGENT_REACH_`, convert the nested key to uppercase, and replace dots with underscores. For example, to override `openai.api_key` in your YAML config, set the environment variable `AGENT_REACH_OPENAI_API_KEY`. The `Config.load()` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) automatically transforms this back to dot notation when parsing.

### What happens if the HOME environment variable is not set?

Agent Reach falls back to the current directory. In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), line 32 uses `os.getenv("HOME", ".")`, meaning if `HOME` is undefined, it attempts to create or read from [`./.agent_reach/config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/./.agent_reach/config.yaml). However, the `Probe.check()` method will flag `"home_set": False` in diagnostics, indicating a non-standard environment.

### Are OpenAI and ElevenLabs API keys required for basic operation?

No. While the `.env.example` file lists these variables and some channels may leverage these services, Agent Reach's core functionality does not require them. The framework checks for channel-specific variables like `TWITTER_COOKIE` or `EXA_API_KEY` at initialization, but OpenAI integration typically occurs only when specific LLM-powered channels are invoked.

### Why does Agent Reach use cookies instead of OAuth tokens for authentication?

The channel implementations in `agent_reach/channels/` (including Twitter, Reddit, and Xiaohongshu) use cookie-based authentication via environment variables like `TWITTER_COOKIE` to simplify deployment in headless environments. This approach avoids the need for interactive OAuth flows during runtime, though it requires users to manually extract and export cookie strings from browser sessions.