# How Agent Reach Securely Manages Credentials in config.yaml

> Learn how Agent Reach securely manages credentials in config.yaml using strict permissions, isolated directories, and environment variable overrides. Secure your sensitive tokens today.

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

---

**Agent Reach protects sensitive tokens and API keys by storing them in `~/.agent-reach/config.yaml` with strict 0o600 file permissions, isolated user directories, and optional environment variable overrides, while continuously auditing permissions via a built-in diagnostic tool.**

Agent Reach implements a defense-in-depth strategy for credential management that keeps secrets out of source code and environment files. By leveraging Unix file permissions, isolated configuration directories, and runtime security checks, the framework ensures that API keys and authentication tokens remain accessible only to the owner. This article examines the specific security mechanisms implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) that govern how secrets are persisted and protected.

## Isolated Configuration Directory

Agent Reach creates a dedicated, hidden directory for all configuration data to prevent accidental exposure. The `Config` class defines the path constants at lines 18-20 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), establishing `~/.agent-reach/` as the configuration root and [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) as the secure credential store.

On first initialization, the library automatically creates this directory if it does not exist. This isolation ensures that credential files never reside in world-readable locations like `/tmp` or the project root, reducing the attack surface for unauthorized access.

## Restricted File Permissions

When persisting credentials to disk, Agent Reach eliminates the race condition where a file might be temporarily world-readable during creation. The `Config.save()` method (lines 52-60 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) uses `os.open` with the mode `0o600` (read-write for owner only) combined with `stat.S_IRUSR | stat.S_IWUSR` flags.

This atomic approach ensures that from the moment the file is created, only the user who owns the process can read or modify the contents. The framework explicitly prevents group-read and other-read bits from being set, blocking access by other users on shared systems.

## Environment Variable Fallback

For users who prefer to keep secrets entirely out of the filesystem, Agent Reach provides a secure fallback mechanism. The `Config.get()` method (lines 70-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) implements a priority lookup that first checks the in-memory YAML data, then queries environment variables using `os.environ.get(key.upper())`.

This design allows sensitive values to be injected via secure secret management systems or CI/CD pipelines while maintaining backward compatibility with file-based configuration. If an environment variable exists with the same name (converted to uppercase), it overrides the YAML value, providing flexibility without compromising security.

## Runtime Permission Auditing

Agent Reach includes a proactive security monitoring feature through the `doctor` command. Implemented in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 14-23), this diagnostic inspects the UNIX mode bits of [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) during execution.

If the verification detects that group-read or world-read permissions are set, the tool immediately warns the user and recommends running `chmod 600` to restore secure access controls. This continuous auditing ensures that accidental permission changes or backup restores do not leave credentials exposed.

## Secure YAML Processing

Beyond filesystem protections, Agent Reach mitigates deserialization attacks by using `yaml.safe_load` for all configuration parsing. When writing data, the `Config.save()` method employs `yaml.dump` with `allow_unicode=True`, ensuring that arbitrary Python objects cannot be executed during configuration loading.

This prevents malicious YAML payloads from compromising the system when configuration files are shared or edited manually.

## Practical Implementation

The following examples demonstrate how to interact with Agent Reach's secure credential management:

```python
from pathlib import Path
from agent_reach.config import Config

# Initialize the configuration handler (creates ~/.agent-reach/ if needed)

cfg = Config()

# Store a sensitive API key (automatically writes with 0o600 permissions)

cfg.set("openai_api_key", "sk-xxxxxxxxxxxxxxxxxxxx")

# Retrieve a credential (checks YAML first, then environment variables)

api_key = cfg.get("openai_api_key")
print("Key prefix:", api_key[:8])  # Always mask in logs

# Remove sensitive data

cfg.delete("openai_api_key")

```

Run the built-in diagnostic to verify file permissions:

```bash
python -m agent_reach.cli doctor

# Warning appears if config.yaml is not mode 600

```

## Summary

Agent Reach implements multiple layers of protection for credential security:

- **Isolated directory**: Credentials reside in `~/.agent-reach/`, separate from application code
- **Strict permissions**: Files are created with `0o600` mode using atomic `os.open` operations
- **Environment override**: `Config.get()` checks uppercase environment variables before file values
- **Continuous auditing**: The `doctor` command verifies permissions and warns against insecure configurations
- **Safe serialization**: `yaml.safe_load` prevents arbitrary code execution during configuration parsing

## Frequently Asked Questions

### Where does Agent Reach store the config.yaml file?

Agent Reach stores the configuration file at `~/.agent-reach/config.yaml` within the user's home directory. The `Config` class defines these paths at lines 18-20 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), creating the hidden directory automatically on first use to ensure credentials remain in a user-private location.

### What file permissions does Agent Reach use for credentials?

The framework uses Unix mode `0o600` (read-write for owner only) when creating or modifying [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml). In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 52-60), the `Config.save()` method opens files with `os.open` using `stat.S_IRUSR | stat.S_IWUSR` flags, ensuring group and other users cannot access the file contents.

### Can I use environment variables instead of the config file?

Yes. The `Config.get()` method (lines 70-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) implements a fallback chain that checks for uppercase environment variables after inspecting the YAML file. This allows you to export `OPENAI_API_KEY` in your shell and have it override any value stored in [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml), keeping secrets out of the filesystem entirely.

### How do I verify that my credentials are properly secured?

Run the diagnostic command `python -m agent_reach.cli doctor`, which executes the permission audit in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 14-23). This inspects the file mode bits of [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) and generates a warning if group-read or world-read permissions are detected, advising you to execute `chmod 600` to restore secure access controls.