# Agent Reach Environment Variables: Complete Configuration Guide

> Discover Agent Reach environment variables for seamless API authentication and service configuration. Learn how to override local settings for maximum flexibility.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-15

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py), you must provide both values:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) module checks for API keys in environment variables to select the appropriate provider.

**Groq Whisper** requires:

```bash
export GROQ_API_KEY="gsk_XXXXXXXXXXXXXXXX"

```

**OpenAI Whisper** requires:

```bash
export OPENAI_API_KEY="sk-XXXXXXXXXXXXXXXX"

```

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

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

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

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py), for the Twitter integration to authenticate properly.