# Config File Location for Agent Reach: Complete Path Reference

> Find the exact Agent Reach config file location at ~/.agent-reach/config.yaml. Learn how CONFIG_DIR and CONFIG_FILE constants define the path in the agent_reach/config.py file.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: api-reference
- Published: 2026-06-25

---

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

This results in the absolute path:

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

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

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

```python

# 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:

```python

# 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:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: The CLI entry point loads 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 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py)) and core engine ([`core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.