Agent Reach Environment Variables: Complete Configuration Guide

Agent Reach reads uppercase environment variables for API authentication and service configuration, overriding values stored in ~/.agent-reach/config.yaml when present.

Agent Reach supports external service configuration through shell environment variables. The Config class in agent_reach/config.py defines a FEATURE_REQUIREMENTS mapping that links each optional integration to specific configuration keys and their corresponding environment variable names.

Feature-Specific Environment Variables

Agent Reach recognizes specific environment variables for each external service integration. These variables take precedence over YAML configuration values when set.

Exa Search Configuration

For Exa search functionality, Agent Reach requires the exa_api_key configuration. Set the corresponding environment variable to authenticate requests:

export EXA_API_KEY="your_exa_api_key_here"

Twitter XReach Authentication

The Twitter XReach feature requires two separate tokens for authentication. According to the source code in agent_reach/channels/twitter.py, you must provide both values:

export TWITTER_AUTH_TOKEN="your_auth_token"
export TWITTER_CT0="your_ct0_cookie_value"

Transcription Services (Groq and OpenAI)

Agent Reach supports multiple transcription backends. The agent_reach/transcribe.py module checks for API keys in environment variables to select the appropriate provider.

Groq Whisper requires:

export GROQ_API_KEY="gsk_XXXXXXXXXXXXXXXX"

OpenAI Whisper requires:

export OPENAI_API_KEY="sk-XXXXXXXXXXXXXXXX"

In agent_reach/cli.py, the CLI explicitly checks os.environ.get("GROQ_API_KEY") before falling back to the configuration file value.

GitHub Integration

For GitHub integration, set the token in your shell environment:

export GITHUB_TOKEN="ghp_your_personal_access_token"

Runtime and Display Environment Variables

Beyond API authentication, Agent Reach checks several generic environment variables that affect CLI behavior and output formatting.

AGENT_REACH_LANG controls the preferred language for the CLI interface. This allows users to override default locale settings without modifying configuration files.

Display Detection variables (DISPLAY and WAYLAND_DISPLAY) determine whether a graphical display is available. Agent Reach uses these to adjust color output and formatting for terminal environments.

SSH Detection variables (SSH_CONNECTION and SSH_CLIENT) identify when the process runs inside an SSH session, potentially triggering alternate output modes for remote terminals.

PYTEST_CURRENT_TEST serves as an internal flag used during test execution to modify behavior during test runs.

How Configuration Lookup Works in Agent Reach

The configuration resolution follows a specific precedence order implemented in the Config class. When the system requests a configuration key, the lookup process executes as follows:

1. YAML File Check: Config.get(key) first attempts to read the value from ~/.agent-reach/config.yaml.
2. Environment Variable Fallback: If the key is absent from the YAML file, the code calls os.environ.get(key.upper()) to check for an uppercase environment variable version.
3. Explicit CLI Checks: Some modules in agent_reach/cli.py perform direct environment checks using bool(os.environ.get("GROQ_API_KEY")) before consulting the Config object, though the result remains consistent.

This implementation means that environment variables override configuration file values. For example, if GITHUB_TOKEN exists in the shell environment, Agent Reach uses that value even if a different token is stored in the YAML configuration.

Practical Examples for Setting Environment Variables

Temporary Session Configuration

Set variables for a single command execution:

export GROQ_API_KEY="gsk_XXXXXXXXXXXXXXXX"
agent-reach transcribe "https://example.com/audio.mp3"

The CLI detects the environment variable and uses it for Groq-based transcription without requiring a config file entry.

Persistent Configuration via Python API

Alternatively, populate the YAML configuration file using the Python API:

from agent_reach.config import Config

cfg = Config()
cfg.set("groq_api_key", "gsk_XXXXXXXXXXXXXXXX")

This saves the value to ~/.agent-reach/config.yaml, allowing subsequent commands to run without environment variables.

Multiple Service Configuration

Configure multiple services simultaneously for automated installation:

export EXA_API_KEY="your_exa_key"
export TWITTER_AUTH_TOKEN="your_twitter_token"
export TWITTER_CT0="your_twitter_ct0"
agent-reach install --env=auto

The installer detects all three services through the provided environment variables.

Summary

• Agent Reach reads uppercase environment variables that map to lowercase configuration keys defined in agent_reach/config.py.
• API keys for Exa, Twitter, Groq, OpenAI, and GitHub can be set via EXA_API_KEY, TWITTER_AUTH_TOKEN, TWITTER_CT0, GROQ_API_KEY, OPENAI_API_KEY, and GITHUB_TOKEN respectively.
• Environment variables take precedence over values stored in ~/.agent-reach/config.yaml.
• The Config.get() method implements the lookup logic, checking the YAML file first, then falling back to os.environ.get(key.upper()).
• Runtime variables like AGENT_REACH_LANG, DISPLAY, and SSH_CONNECTION control CLI behavior and output formatting.

Frequently Asked Questions

Does Agent Reach require environment variables to function?

No. Agent Reach can store all configuration values in the YAML file at ~/.agent-reach/config.yaml. However, environment variables provide a secure method for credential management in CI/CD pipelines and containerized environments without writing secrets to disk.

What happens if both an environment variable and config file value exist for the same key?

The environment variable takes precedence. When Config.get() resolves a key, it returns the environment variable value if present, overriding any stored configuration. The CLI modules in agent_reach/cli.py explicitly check os.environ first for certain critical keys like GROQ_API_KEY.

Are environment variable names case-sensitive in Agent Reach?

Yes. The code converts configuration keys to uppercase when checking environment variables using key.upper(). Therefore, groq_api_key in the config file corresponds to GROQ_API_KEY in the environment, and github_token corresponds to GITHUB_TOKEN.

Can I use environment variables for the Twitter XReach feature?

Yes. Twitter XReach requires two environment variables: TWITTER_AUTH_TOKEN and TWITTER_CT0. Both must be set simultaneously in your shell environment, as implemented in agent_reach/channels/twitter.py, for the Twitter integration to authenticate properly.

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