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

> Learn about Agent Reach's local credential storage security model. Discover how 0o600 file permissions protect your tokens and API keys, ensuring user account privacy.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: deep-dive
- Published: 2026-06-19

---

**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`](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 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python

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

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles permission enforcement automatically:

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

```bash
$ 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- **Runtime validation**: The `doctor` command in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.