Configuration File Location for Agent Reach: Default Path and Custom Setup

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

The open-source Agent Reach project by Panniantong manages user settings through a centralized configuration system. Understanding the configuration file location for Agent Reach is essential for debugging, backing up credentials, or deploying the tool in containerized environments. The repository implements a secure, YAML-based configuration manager that automatically handles file creation and permissions.

Default Configuration File Location

According to the source code in agent_reach/config.py (lines 18-20), Agent Reach defines two critical constants that determine where settings persist:

• CONFIG_DIR: Resolves to ~/.agent-reach (a hidden directory in the user's home folder)
• CONFIG_FILE: Points to config.yaml inside that directory

This results in the absolute default path:

~/.agent-reach/config.yaml

When a Config instance is created without arguments, it automatically resolves to this location.

Initializing and Customizing the Config Path

The Config class constructor accepts an optional config_path parameter. If omitted, it defaults to the standard 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

For testing scenarios or multi-environment deployments, pass a pathlib.Path object to override the default:

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

File Security and Directory Initialization

The Config class implements security-conscious file handling through the _ensure_dir() method. When writing configurations, it creates the directory structure if missing, then initializes the file with mode 600 (read/write for owner only). This protects sensitive credentials like API keys and authentication tokens stored in the YAML file from unauthorized access.

Reading and Writing Configuration Values

The configuration file follows standard YAML format. The Config class provides methods to interact with these settings programmatically.

Reading values with automatic environment variable fallback:

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

Persisting new values:

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

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

Verifying feature readiness:

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

Integration with CLI and Core Modules

The configuration system integrates across the Agent Reach codebase:

• agent_reach/cli.py: Loads settings for CLI commands like doctor and install
• agent_reach/core.py: Consults the Config instance to determine feature availability and routing logic

Summary

• Agent Reach stores configuration in ~/.agent-reach/config.yaml by default, as defined in agent_reach/config.py
• The Config class exposes path customization through the config_path parameter for testing or isolated deployments
• Configuration files are created with mode 600 permissions to secure stored credentials
• Methods get(), set(), and is_configured() provide the primary interface for interacting with settings
• The configuration manager is integrated into both the CLI entry point and core routing logic

Frequently Asked Questions

Where does Agent Reach store its configuration file by default?

Agent Reach stores its configuration in ~/.agent-reach/config.yaml. This path is hardcoded in agent_reach/config.py through the CONFIG_DIR and CONFIG_FILE constants (lines 18-20), which resolve to a hidden directory in the user's home folder.

Can I specify a custom configuration file location?

Yes. While the Config class defaults to ~/.agent-reach/config.yaml, you can override this by passing a pathlib.Path object to the config_path parameter when instantiating Config. This flexibility supports testing environments and multi-tenant deployments.

What permissions does Agent Reach set on the configuration file?

The Config class creates the configuration file with mode 600 (read and write permissions restricted to the file owner). This security measure ensures that sensitive credentials like API keys and tokens remain protected from other system users.

Which source files handle configuration management in Agent Reach?

Configuration logic is centralized in agent_reach/config.py, which defines the Config class and default path constants. The CLI interface in agent_reach/cli.py utilizes this class for commands like doctor and install, while agent_reach/core.py consults it to determine feature availability and routing behavior.

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