# Agent Reach Configuration File Format and Location: Complete Guide

> Discover the Agent Reach configuration file format and location. Learn where your user-specific settings are stored in the handy config.yaml file.

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

---

**Agent Reach stores user-specific settings in a YAML file at `~/.agent-reach/config.yaml`, with the location defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) within that directory

When you instantiate the `Config` class without arguments, it automatically resolves to this default 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

```

## Custom Configuration File Paths

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

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

```

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:

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

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

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – The CLI entry point uses `Config` to load settings for commands like `doctor` and `install`
- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.