Environment Variables That Control Agent Reach Behavior: Complete Configuration Guide

Agent Reach reads configuration from environment variables including AGENT_REACH_CONFIG, LOG_LEVEL, and platform-specific credentials like TWITTER_COOKIE and GITHUB_TOKEN, which are loaded at startup in agent_reach/config.py and agent_reach/cli.py.

Agent Reach is an open-source automation framework that relies on environment variables to control everything from logging verbosity to platform authentication. Understanding which environment variables control Agent Reach behavior is essential for customizing deployments across development and production environments. The codebase reads these variables early in the program lifecycle, with central parsing logic located in the configuration module and CLI entry point.

Core System Variables

Three primary environment variables govern how Agent Reach initializes its runtime environment, configuration loading, and logging output.

AGENT_REACH_CONFIG

The AGENT_REACH_CONFIG variable specifies the absolute path to a custom YAML configuration file. When this variable is not set, Agent Reach falls back to the default config.yaml located in the repository root. This variable is parsed in agent_reach/config.py, which serves as the central configuration loader for the entire application.

AGENT_REACH_ENV

The AGENT_REACH_ENV variable selects the runtime environment mode for the installer and diagnostic tools. Acceptable values include auto, dev, and prod. This setting is processed by the CLI entry point in agent_reach/cli.py before any platform-specific logic executes, ensuring the correct behavior profile is active during initialization.

LOG_LEVEL

The LOG_LEVEL variable controls the verbosity of the internal loguru logger. Valid values are DEBUG, INFO, WARNING, and ERROR. This variable is read in agent_reach/cli.py during the logging setup phase, allowing you to adjust output granularity without modifying code.

Platform Authentication Variables

Agent Reach integrates with multiple social media platforms and APIs, each requiring specific credential environment variables.

Social Media Cookies

Cookie-based authentication uses exported browser cookies for platforms that require authenticated sessions:

• TWITTER_COOKIE: Authentication cookie string for Twitter/X API access, consumed in agent_reach/channels/twitter.py
• XHS_COOKIE: Cookie string for Xiaohongshu (Little Red Book) platform authentication, read in agent_reach/channels/xiaohongshu.py
• BILIBILI_COOKIE: Cookie string required for authenticated video access on Bilibili, parsed in agent_reach/channels/bilibili.py

API Keys and OAuth Credentials

Token-based authentication for official APIs:

• REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET: OAuth client credentials required for Reddit API access, used in agent_reach/channels/reddit.py
• GITHUB_TOKEN: Personal access token for GitHub API authentication when querying repositories or issues, read in agent_reach/channels/github.py
• YOUTUBE_API_KEY: API key for YouTube Data API v3, enabling video search and metadata retrieval in agent_reach/channels/youtube.py

Network and Integration Settings

Additional variables control network connectivity and external service integration.

Proxy Configuration

The HTTP_PROXY and HTTPS_PROXY variables configure proxy settings used by the internal requests session. These are processed in agent_reach/utils/process.py when the application reaches out to external APIs such as Twitter, Reddit, and YouTube.

MCP Server Integration

Variables for the Message-Control-Protocol server integration:

• MCP_SERVER_URL: Base URL of the MCP server
• MCP_AUTH_TOKEN: Authentication token for MCP server requests

Both variables are read in agent_reach/integrations/mcp_server.py and are required when using the MCP integration features.

How Environment Variables Are Loaded

Agent Reach follows a specific initialization sequence for environment variable processing.

First, the CLI entry point in agent_reach/cli.py parses command-line arguments and checks for AGENT_REACH_ENV and LOG_LEVEL. Then, the configuration loader in agent_reach/config.py imports settings from the YAML file specified by AGENT_REACH_CONFIG, merging environment variables with file-based configuration.

Platform-specific channel implementations lazy-load their respective credentials when instantiated. For example, agent_reach/channels/twitter.py reads TWITTER_COOKIE during the TwitterChannel class initialization, raising a clear error if the variable is missing.

Practical Configuration Examples

Set up your environment before running Agent Reach commands:

# Configure system behavior

export AGENT_REACH_CONFIG="/path/to/production.yaml"
export AGENT_REACH_ENV="prod"
export LOG_LEVEL="DEBUG"

# Set platform credentials

export TWITTER_COOKIE="auth_token=abc123; ct0=xyz789"
export YOUTUBE_API_KEY="AIzaSyYourApiKeyHere"
export GITHUB_TOKEN="ghp_yourpersonalaccesstoken"

# Configure network proxy

export HTTPS_PROXY="http://proxy.company.com:8080"

# Run the diagnostic doctor

python -m agent_reach.cli doctor

Programmatically configure variables before importing Agent Reach modules:

import os
os.environ["AGENT_REACH_CONFIG"] = "/path/to/my_config.yaml"
os.environ["LOG_LEVEL"] = "INFO"

from agent_reach.cli import main
main(["install", "--env=auto"])

Accessing credentials within a custom channel implementation:

import os
from loguru import logger

class TwitterChannel:
    def __init__(self):
        self.cookie = os.getenv("TWITTER_COOKIE")
        if not self.cookie:
            logger.error("TWITTER_COOKIE not set – authentication will fail")
            raise ValueError("Missing required environment variable: TWITTER_COOKIE")

Summary

• AGENT_REACH_CONFIG defines the path to your YAML configuration file, parsed in agent_reach/config.py
• AGENT_REACH_ENV and LOG_LEVEL control runtime mode and logging verbosity in agent_reach/cli.py
• Platform credentials like TWITTER_COOKIE, GITHUB_TOKEN, and REDDIT_CLIENT_ID are read by their respective channel implementations in agent_reach/channels/
• Network proxy settings (HTTP_PROXY/HTTPS_PROXY) are handled in agent_reach/utils/process.py
• MCP integration requires MCP_SERVER_URL and MCP_AUTH_TOKEN in agent_reach/integrations/mcp_server.py

Frequently Asked Questions

How do I specify a custom configuration file for Agent Reach?

Set the AGENT_REACH_CONFIG environment variable to the absolute path of your YAML file. If this variable is not present, Agent Reach defaults to the config.yaml file in the repository root directory. The configuration loader in agent_reach/config.py processes this variable during application startup.

Which environment variables are required for social media authentication?

Required variables depend on which platforms you use. For Twitter/X, you need TWITTER_COOKIE. For Reddit, you need REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET. For GitHub integration, GITHUB_TOKEN is required. Each channel implementation checks for its specific credentials during initialization and provides clear error messages if variables are missing.

How do I configure proxy settings for Agent Reach?

Set the HTTP_PROXY and HTTPS_PROXY environment variables to your proxy server URLs. Agent Reach reads these variables in agent_reach/utils/process.py and applies them to the internal requests session used for all external API calls. This configuration affects connectivity to Twitter, Reddit, YouTube, and other external services.

Where does Agent Reach load environment variables from?

Agent Reach reads environment variables using Python's os.getenv() calls distributed across the codebase. Central loading occurs in agent_reach/config.py for general configuration and agent_reach/cli.py for runtime settings. Platform-specific variables are read lazily by individual channel classes in agent_reach/channels/ when the respective platform is accessed.

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