How Agent Reach Securely Manages Credentials in config.yaml

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 and 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, establishing ~/.agent-reach/ as the configuration root and 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) 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) 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 (lines 14-23), this diagnostic inspects the UNIX mode bits of 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:

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:

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, 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. In 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) 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, 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 (lines 14-23). This inspects the file mode bits of 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.

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