Agent Reach Configuration File Format and Location: Complete Guide

Agent Reach stores user-specific settings in a YAML file at ~/.agent-reach/config.yaml, with the location defined in agent_reach/config.py by the CONFIG_DIR and CONFIG_FILE constants.

The Panniantong/Agent-Reach repository uses a centralized configuration system to manage user credentials and feature settings. Understanding the Agent Reach configuration file format and location is essential for customizing the tool, troubleshooting connectivity issues, or migrating settings between environments.

Default Configuration File Location

Agent Reach stores its user-specific settings in a hidden folder inside the user’s home directory. The default path is:

~/.agent-reach/config.yaml

This location is defined in agent_reach/config.py (lines 18-20) by two constants:

• CONFIG_DIR – Points to .agent-reach/ in the user's home directory
• CONFIG_FILE – Specifies config.yaml within that directory

When you instantiate the Config class without arguments, it automatically resolves to this default location:

from agent_reach.config import Config

# Uses the default location (~/.agent-reach/config.yaml)

cfg = Config()
print(cfg.config_path)          # → /home/<user>/.agent-reach/config.yaml

Custom Configuration File Paths

For testing or isolated environments, you can specify a custom path by passing a Path object to the constructor:

from pathlib import Path
from agent_reach.config import Config

custom_cfg = Config(config_path=Path("/tmp/my-config.yaml"))
print(custom_cfg.config_path)   # → /tmp/my-config.yaml

This flexibility allows you to maintain separate configuration profiles for different projects or CI/CD pipelines without modifying the default location.

Configuration File Format

Agent Reach uses YAML format for its configuration files. The Config class creates the file with strict permissions (mode 600) to protect stored credentials such as API keys and tokens.

The configuration file stores key-value pairs that can be accessed throughout the application. Before writing any data, the Config class ensures the configuration directory exists through the _ensure_dir() method.

Reading and Writing Configuration Values

Reading Values with Environment Fallback

The get() method retrieves values from the YAML file, with automatic fallback to environment variables if the key is absent:

api_key = cfg.get("openai_api_key")
if api_key:
    print("OpenAI API key is configured")
else:
    print("OpenAI API key not set")

Saving Configuration Values

Use the set() method to write values to the configuration file. Changes are persisted automatically to ~/.agent-reach/config.yaml:

cfg.set("github_token", "ghp_XXXXXXXXXXXXXXXXXXXX")

# The file is written to ~/.agent-reach/config.yaml automatically.

Checking Feature Configuration

The is_configured() method verifies whether a specific feature has all required settings:

if cfg.is_configured("twitter_xreach"):
    print("Twitter XReach ready")
else:
    print("Missing Twitter credentials")

Integration with Agent Reach Components

The configuration system is integrated across the codebase to provide centralized settings management:

• agent_reach/cli.py – The CLI entry point uses Config to load settings for commands like doctor and install
• agent_reach/core.py – Core routing logic consults Config to determine feature availability based on user credentials

Summary

• Agent Reach stores configuration in ~/.agent-reach/config.yaml by default, as defined in agent_reach/config.py
• The location is controlled by the CONFIG_DIR and CONFIG_FILE constants (lines 18-20)
• File format is YAML with 600 permissions for security
• Use Config() for the default path or Config(config_path=Path(...)) for custom locations
• The get(), set(), and is_configured() methods manage configuration values with automatic environment variable fallback

Frequently Asked Questions

Where does Agent Reach store its configuration file?

Agent Reach stores user-specific settings in a hidden folder .agent-reach inside the user's home directory, specifically at ~/.agent-reach/config.yaml. This path is hardcoded in agent_reach/config.py through the CONFIG_DIR and CONFIG_FILE constants.

What format does the Agent Reach configuration file use?

The configuration file uses YAML format. When created by the Config class, the file is assigned strict permissions (mode 600) to ensure that sensitive credentials like API keys remain accessible only to the file owner.

Can I use a custom configuration file location with Agent Reach?

Yes, you can specify a custom path by passing a Path object to the Config constructor. For example: Config(config_path=Path("/tmp/my-config.yaml")). This is useful for testing environments or when you need to maintain separate configuration profiles.

How does Agent Reach handle missing configuration values?

The Config.get() method automatically falls back to environment variables if a key is not present in the YAML configuration file. This allows you to keep sensitive credentials in environment variables while storing non-sensitive settings in the configuration file.

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