Config File Location for Agent Reach: Complete Path Reference

Agent Reach stores user-specific settings in ~/.agent-reach/config.yaml by default, with the path defined by the CONFIG_DIR and CONFIG_FILE constants in agent_reach/config.py.

When working with the Panniantong/Agent-Reach repository, understanding where configuration files reside is essential for managing API keys and feature settings. The config file location for Agent Reach follows a standardized pattern, placing user-specific YAML settings in a hidden directory within the home folder. This design ensures that sensitive credentials remain isolated from project directories while remaining accessible to the CLI and core modules.

Default Config File Location

Agent Reach follows the XDG-compliant convention of storing user configuration in the home directory. According to the source code in agent_reach/config.py, the default location is determined by two constants defined at lines 18-20:

• CONFIG_DIR: Points to ~/.agent-reach
• CONFIG_FILE: Resolves to config.yaml within that directory

This results in the absolute path:

~/.agent-reach/config.yaml

The Config class automatically resolves to this location when instantiated without arguments, creating the directory structure if it does not exist.

How the Config Class Resolves Paths

The configuration system distinguishes between default and custom locations through the Config class constructor. When initializing the configuration manager, you can either accept the default path or specify an alternative.

Using the default location:

from agent_reach.config import Config

# Resolves to ~/.agent-reach/config.yaml

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

Specifying a custom path:

from pathlib import Path
from agent_reach.config import Config

# Override the default location

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

Configuration File Security and Initialization

The Config class implements security-conscious file handling through the _ensure_dir method. When a configuration instance is created, the system automatically:

1. Creates the .agent-reach directory if absent
2. Initializes the YAML file with strict permissions (mode 600) to protect stored credentials
3. Ensures parent directories exist before writing

This permission model prevents other system users from reading API keys or tokens stored in the configuration file.

Reading and Writing Configuration Values

Once the config file location is established, the Config class provides methods for persistent storage and retrieval.

Reading Configuration Values

The get method retrieves values from the YAML file, with fallback support for environment variables:

# Retrieve OpenAI API key (checks env var if not in file)

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

The set method writes values to the config file location immediately:

# Store GitHub token (writes to ~/.agent-reach/config.yaml)

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

Checking Feature Configuration

The is_configured method verifies whether all required settings for a specific feature are present:

# Check if Twitter XReach has necessary credentials

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

Integration with CLI and Core Modules

The configuration system serves as the central authority for the Agent Reach ecosystem. The Config class is imported and utilized across multiple modules:

• agent_reach/cli.py: The CLI entry point loads settings for commands like doctor and install
• agent_reach/core.py: Core routing logic consults the configuration to determine feature availability and API endpoints

These integrations ensure that the ~/.agent-reach/config.yaml file acts as the single source of truth for user preferences across the application.

Summary

• Agent Reach stores configuration in ~/.agent-reach/config.yaml by default, as defined in agent_reach/config.py
• The Config class constructor accepts an optional config_path parameter to override the default location
• File permissions are set to mode 600 upon creation to secure sensitive credentials
• Methods like get(), set(), and is_configured() provide a Pythonic interface for configuration management
• Both the CLI (cli.py) and core engine (core.py) rely on this centralized configuration system

Frequently Asked Questions

Where is the Agent Reach config file stored on Linux and macOS?

By default, Agent Reach creates a hidden directory named .agent-reach in your home folder and stores settings in config.yaml within that directory. The full path resolves to ~/.agent-reach/config.yaml, as implemented in the CONFIG_DIR and CONFIG_FILE constants.

Can I change the default config file location for Agent Reach?

Yes, you can specify a custom path by passing a Path object to the Config constructor. Instantiate Config(config_path=Path("/your/custom/path.yaml")) to override the default ~/.agent-reach/config.yaml location, which is useful for testing or containerized environments.

What permissions does the Agent Reach config file use?

The configuration file is created with mode 600 (read/write for owner only) to protect sensitive information like API keys and tokens. The Config class enforces this permission level automatically when initializing the file through the internal _ensure_dir method.

How does Agent Reach handle missing configuration values?

The Config.get() method checks for values in the YAML file first, then falls back to environment variables if the key is absent. For feature-specific validation, use Config.is_configured("feature_name") to verify that all required settings for a particular integration are present before execution.

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