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

> Discover the Agent Reach configuration file location. Learn the default path ~/.agent-reach/config.yaml and how to set up a custom configuration.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) inside that directory

This results in the absolute default path:

```text
~/.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:

```python
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:

```python
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:

```python
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:**

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

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

```

**Verifying feature readiness:**

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: Loads settings for CLI commands like `doctor` and `install`
- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which defines the `Config` class and default path constants. The CLI interface in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) utilizes this class for commands like `doctor` and `install`, while [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) consults it to determine feature availability and routing behavior.