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

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

• 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) 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 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 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:

# ~/.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, 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

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

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

# The file is automatically written with 0600 permissions.

Checking Feature Readiness

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

Retrieving Values with Environment Fallback

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

api_key = cfg.get("openai_api_key")

Deleting Configuration Keys

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: Uses Config to load settings during command-line execution, particularly for the doctor and install commands
• 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 (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 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.

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