# Environment Variables That Control Agent Reach Behavior: Complete Configuration Guide

> Discover Agent Reach environment variables like AGENT_REACH_CONFIG, LOG_LEVEL, TWITTER_COOKIE, and GITHUB_TOKEN. Master Agent Reach configuration with our complete guide.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: complete-configuration-guide
- Published: 2026-06-24

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) located in the repository root. This variable is parsed in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py)
- **`XHS_COOKIE`**: Cookie string for Xiaohongshu (Little Red Book) platform authentication, read in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py)
- **`BILIBILI_COOKIE`**: Cookie string required for authenticated video access on Bilibili, parsed in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash

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

```python
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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)
- **`AGENT_REACH_ENV`** and **`LOG_LEVEL`** control runtime mode and logging verbosity in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/process.py)
- MCP integration requires **`MCP_SERVER_URL`** and **`MCP_AUTH_TOKEN`** in [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file in the repository root directory. The configuration loader in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) for general configuration and [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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.