Agent Reach Security Model for Local Credential Storage: File Permissions Deep Dive

Agent Reach stores all sensitive tokens, cookies, and API keys in ~/.agent-reach/config.yaml and enforces strict 0o600 file permissions (owner read/write only) at creation time, complemented by runtime validation via the doctor command to ensure credentials remain private to the user account.

The Panniantong/Agent-Reach repository implements a defense-in-depth approach to protect sensitive configuration data on local filesystems. Understanding the security model for storing credentials locally with file permissions in Agent Reach is essential for developers handling API keys and authentication tokens. This article examines the three-layer permission system implemented in agent_reach/config.py and agent_reach/doctor.py that prevents credential leakage through filesystem access controls.

Creation-Time Permission Hardening in agent_reach/config.py

When Agent Reach initializes its configuration store, it does not rely on default file creation modes. Instead, the library explicitly requests restrictive permissions during the atomic file creation process.

Atomic File Creation with os.open

In agent_reach/config.py, the code uses low-level os.open() flags to ensure the file never exists in a world-readable state, even momentarily:

# agent_reach/config.py – creation of the file with safe mode

fd = os.open(
    str(self.config_path),
    os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
    stat.S_IRUSR | stat.S_IWUSR,      # → 0o600

)

This approach sets the file mode to 0o600 (read and write permissions for the owner only) at the moment of creation. By using os.O_CREAT with the mode argument, Agent Reach eliminates the race condition where a file might be created with default permissions and then modified, which could expose credentials to other users on shared systems.

Runtime Validation with the Doctor Command

Agent Reach includes a continuous security monitoring mechanism through the doctor command implemented in agent_reach/doctor.py. This runtime check ensures that file permissions remain restrictive even if external tools or manual modifications have changed them.

The validation logic inspects the actual permission bits of config.yaml:

# agent_reach/doctor.py – runtime permission audit

if config_path.exists() and sys.platform != "win32":
    mode = config_path.stat().st_mode
    if mode & (stat.S_IRGRP | stat.S_IROTH):   # group- or world-readable?

        lines.append("[bold red][!]  安全提示：config.yaml 权限过宽（其他用户可读）[/bold red]")
        lines.append("   修复：chmod 600 ~/.agent-reach/config.yaml")

If the system detects that the file has become group-readable or world-readable, it immediately displays a security warning with the exact remediation command: chmod 600 ~/.agent-reach/config.yaml.

Cross-Platform Security Fallbacks

The security model accounts for platform differences, particularly Windows systems where os.open() with permission flags behaves differently. On platforms that do not support low-level permission flags, Agent Reach falls back to a standard open() call for file creation.

However, the runtime validation layer remains active across all platforms. When the doctor routine runs on Windows, it detects the platform and skips the mode bit check, as Windows relies on ACLs rather than Unix permissions for access control.

Practical Usage and Verification

Working with the secure configuration store follows a straightforward API. The Config class in agent_reach/config.py handles permission enforcement automatically:

>>> from agent_reach.config import Config
>>> cfg = Config()                     # creates ~/.agent-reach/config.yaml if missing

>>> cfg.set("github_token", "ghp_…")   # writes the token with 0o600 permissions

>>> cfg.get("github_token")            # reads from the file (or env var)

'ghp_…'

To verify your credentials remain properly protected, run the diagnostic command:

$ python -m agent_reach.cli doctor
...
[bold red][!]  安全提示：config.yaml 权限过宽（其他用户可读）[/bold red]
   修复：chmod 600 ~/.agent-reach/config.yaml

If the file permissions are correct, the warning is omitted and the command exits silently, confirming your credentials are properly secured.

Summary

• Creation-time hardening: Agent Reach atomically creates ~/.agent-reach/config.yaml with mode 0o600 (owner read/write only) using os.open() with explicit permission flags in agent_reach/config.py.
• Runtime validation: The doctor command in agent_reach/doctor.py inspects file permissions on every execution and provides clear remediation instructions if the file becomes group- or world-readable.
• Graceful fallback: On Windows and other platforms lacking low-level permission flags, the code falls back to standard file operations while relying on the doctor check to surface permission issues.
• Clear remediation: When permissions are too permissive, the system outputs the exact chmod 600 ~/.agent-reach/config.yaml command needed to restore security.

Frequently Asked Questions

What file permissions does Agent Reach use for local credential storage?

Agent Reach creates the ~/.agent-reach/config.yaml file with 0o600 permissions (read and write access for the owner only, no access for group or others). This is enforced atomically at file creation time using stat.S_IRUSR | stat.S_IWUSR flags in the os.open() call within agent_reach/config.py.

How does Agent Reach handle credential storage security on Windows?

On Windows, where Unix-style file permission bits are not supported through os.open(), Agent Reach falls back to a standard open() call for file creation. The runtime permission validation in agent_reach/doctor.py detects the Windows platform and skips the mode bit check, as Windows relies on ACLs rather than Unix permissions for access control.

What happens if the config.yaml file permissions become too permissive?

If the doctor command detects that config.yaml has become group-readable or world-readable (by checking if stat.S_IRGRP or stat.S_IROTH bits are set), it displays a prominent security warning and provides the exact remediation command: chmod 600 ~/.agent-reach/config.yaml. This ensures users can quickly restore proper access controls.

Where does Agent Reach store sensitive credentials locally?

Agent Reach stores all sensitive tokens, cookies, and API keys in ~/.agent-reach/config.yaml. This centralized location allows the library to apply consistent permission controls and auditing across all credential types, preventing fragmentation of sensitive data across multiple files.

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