Agent Reach Environment Variables: Complete Runtime Configuration Guide

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, 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.

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, 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, 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 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 (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 (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 (line 15). The cookie is optional but enables authenticated API requests when provided.

• XIAOYUZHOU_COOKIE: Required by XiaoyuzhouChannel in 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. 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 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, line 32 uses os.getenv("HOME", "."), meaning if HOME is undefined, it attempts to create or read from ./.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.

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