# Agent Reach Config Class and config.yaml Structure: A Complete Guide

> Master the Agent Reach Config class and config.yaml structure. This guide explains how to manage YAML configurations with automatic directory creation and environment variable fallback.

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

---

**The `Config` class in Agent Reach provides a centralized interface for reading, writing, and validating YAML configuration stored at `~/.agent-reach/config.yaml`, with automatic directory creation, file permission management, and environment variable fallback.**

The **Agent Reach Config class** manages all user-specific settings for the Agent Reach framework, handling everything from API keys to feature toggles. Located in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), this helper class ensures sensitive credentials are stored securely while providing convenient Python methods for configuration management. Understanding the relationship between the `Config` class and the [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file structure is essential for properly setting up Agent Reach integrations.

## Config Class Location and File Structure

### Default Configuration Paths

According to the Agent Reach source code, the configuration system uses two primary constants defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py):

- **`CONFIG_DIR`**: Points to `~/.agent-reach/` in the user's home directory
- **`CONFIG_FILE`**: Points to `~/.agent-reach/config.yaml`

The `Config` class automatically creates the `~/.agent-reach` directory if it does not exist during initialization. This ensures first-time users can immediately begin writing configuration without manual directory setup.

### Core Dependencies and Constants

The class implements a `FEATURE_REQUIREMENTS` mapping (lines 22-28 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) that defines which YAML keys must be present for specific optional features to be considered "configured." This mapping allows the system to validate whether individual integrations—such as Twitter or Exa API—have sufficient credentials before attempting to use them.

## Key Methods and Functionality

### Configuration Persistence

The `Config` class handles file I/O through two primary methods:

- **`load()`**: Reads the YAML file from `~/.agent-reach/config.yaml` into the `self.data` dictionary
- **`save()`**: Writes the current state of `self.data` back to disk with **0600 permissions** (read/write for owner only)

The `save()` method automatically handles permission management to ensure sensitive API keys remain inaccessible to other system users.

### Value Access and Modification

Four methods provide the core CRUD operations for configuration values:

- **`get(key, default)`**: Retrieves a value from [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) or falls back to an environment variable (converting the key to uppercase)
- **`set(key, value)`**: Updates the in-memory dictionary and immediately persists changes to disk
- **`delete(key)`**: Removes a key from the configuration and saves the file
- **`to_dict()`**: Returns a masked view of the configuration where sensitive values are truncated for safe display

### Feature Validation

Two specialized methods support feature detection:

- **`is_configured(feature)`**: Checks whether all required keys for a specific feature exist in the current configuration
- **`get_configured_features()`**: Returns a dictionary indicating which optional integrations are ready for use based on the `FEATURE_REQUIREMENTS` mapping

## Configuration File Format and Options

### Expected YAML Structure

The [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file uses a simple flat key-value mapping. Only the keys required by the features you intend to use need to be present. According to the Agent Reach source code, the expected structure includes:

```yaml

# ~/.agent-reach/config.yaml

exa_api_key: YOUR_EXA_API_KEY
twitter_auth_token: YOUR_TWITTER_AUTH_TOKEN
twitter_ct0: YOUR_TWITTER_CT0
groq_api_key: YOUR_GROQ_API_KEY
openai_api_key: YOUR_OPENAI_API_KEY
github_token: YOUR_GITHUB_PERSONAL_TOKEN

# optional custom settings

proxy_url: http://proxy.example.com:8080

```

**Key characteristics:**
- **Flat structure**: All keys exist at the root level of the YAML document
- **String values**: All values are stored as plain strings
- **Feature mapping**: Each key corresponds exactly to identifiers listed in `FEATURE_REQUIREMENTS`
- **Tolerant parsing**: Missing keys are tolerated; features simply report as "not configured" rather than raising errors

### Environment Variable Fallback

When using `cfg.get("key_name")`, the system first checks [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml), then automatically falls back to the environment variable `KEY_NAME` (uppercase). This allows sensitive credentials to be injected via environment variables in CI/CD pipelines or containerized deployments without writing them to disk.

## Usage Examples

### Loading the Configuration

```python
from agent_reach.config import Config

cfg = Config()                     # uses default ~/.agent-reach/config.yaml

print(cfg.to_dict())               # masked view of the stored settings

```

### Setting and Persisting Values

```python
cfg.set("openai_api_key", "sk-abc123...")

# The file is automatically written with 0600 permissions.

```

### Checking Feature Readiness

```python
if cfg.is_configured("twitter_xreach"):
    print("Twitter integration is ready!")
else:
    print("Missing Twitter credentials.")

```

### Retrieving Values with Environment Fallback

```python

# Will first look in config.yaml, then in the environment variable OPENAI_API_KEY

api_key = cfg.get("openai_api_key")

```

### Deleting Configuration Keys

```python
cfg.delete("proxy_url")

```

## Integration with Agent Reach Components

The `Config` class serves as the central configuration hub across the Agent Reach codebase:

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: Uses `Config` to load settings during command-line execution, particularly for the `doctor` and `install` commands
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: Calls `Config.get_configured_features()` to report which optional integrations are active and properly configured

These integrations demonstrate how the configuration system decouples credential management from feature implementation, allowing the CLI and diagnostic tools to verify readiness before attempting API calls.

## Summary

- The **Agent Reach Config class** is implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 15-111) and manages configuration at `~/.agent-reach/config.yaml`.
- **Security features** include automatic directory creation and 0600 file permissions for sensitive data protection.
- **Dual retrieval** supports both YAML file values and environment variable fallbacks via the `get()` method.
- **Feature validation** uses the `FEATURE_REQUIREMENTS` mapping to check if required keys exist for specific integrations.
- **Safe display** is provided by `to_dict()`, which masks sensitive values when showing configuration status.

## Frequently Asked Questions

### Where is the Agent Reach config file stored?

By default, Agent Reach stores configuration at `~/.agent-reach/config.yaml` in the user's home directory. The `Config` class automatically creates this directory structure if it does not exist when the class is instantiated.

### What permissions does Agent Reach use for the config file?

Agent Reach writes the [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) file with **0600 permissions** (read and write for the owner only, no access for group or others). This security measure ensures that sensitive API keys and tokens remain private to the user who created them.

### How does Agent Reach handle sensitive configuration values?

The `to_dict()` method returns a masked view of the configuration where sensitive values are truncated, making it safe to print or log configuration state. Additionally, the `save()` method enforces strict file permissions (0600) to prevent unauthorized access to the actual YAML file on disk.

### Can Agent Reach use environment variables instead of config.yaml?

Yes. The `get(key, default)` method checks for environment variables as a fallback mechanism. When requesting a value like `openai_api_key`, the system first checks the YAML file, then looks for the `OPENAI_API_KEY` environment variable (uppercase conversion of the key), allowing credentials to be provided via environment configuration without modifying the config file.