# Security Considerations for Agent-Reach Config File Permissions: A Complete Guide

> Secure your Agent-Reach config files with strict filesystem permissions. Learn how to protect sensitive credentials like API keys and tokens from unauthorized access. A complete guide for enhanced security.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: best-practices
- Published: 2026-07-13

---

**Agent-Reach enforces strict filesystem permissions (directory mode `0o700` and file mode `0o600`) on its configuration files to protect sensitive credentials like API keys and tokens from unauthorized access.**

The Agent-Reach library stores user-specific authentication data in `~/.agent-reach/config.yaml`, requiring robust security measures to prevent credential leakage. Understanding the security considerations for Agent-Reach config file permissions is essential for developers handling sensitive API keys, OAuth tokens, and browser cookies. The codebase implements defense-in-depth strategies spanning directory creation, file access controls, and runtime masking across both POSIX and Windows platforms.

## Configuration File Location and Sensitivity

Agent-Reach persists configuration data in a YAML file located at `~/.agent-reach/config.yaml`. This path resides within a hidden directory in the user's home folder, specifically designed to store high-sensitivity values including API keys, access tokens, and session cookies.

Because these credentials grant access to external services and user accounts, the library treats the configuration directory as a **private vault**. The implementation follows the principle of least privilege, ensuring that only the owning user account can read or modify these files.

## Permission Enforcement Mechanisms

Agent-Reach implements multiple layers of filesystem protection during initialization and write operations. These mechanisms operate differently across platforms but maintain consistent security intent.

### Private Directory Creation (0o700)

When the `Config` class initializes, it creates the configuration directory with restrictive permissions using the `make_private_dir` helper function. In [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py), this function explicitly sets directory mode to `0o700` (owner read/write/execute only) and applies `os.chmod` on non-Windows systems.

The initialization occurs in `Config.__init__` at lines 33-36 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py):

```python
from agent_reach.utils.paths import make_private_dir

class Config:
    def __init__(self):
        self.config_dir = Path.home() / ".agent-reach"
        make_private_dir(self.config_dir)  # Mode 0o700 enforced

```

This prevents other users from listing or accessing the directory contents, even if they have broader filesystem access.

### Secure File Creation (0o600)

When writing configuration changes, Agent-Reach avoids race conditions by using `os.open` with atomic permission flags. The `Config.save` method at lines 54-62 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) opens the file with `stat.S_IRUSR | stat.S_IWUSR` (octal `0o600`), ensuring the file is created with user-only read/write permissions:

```python
import os
import stat

def save(self):
    flags = os.O_CREAT | os.O_WRONLY | os.O_TRUNC
    mode = stat.S_IRUSR | stat.S_IWUSR  # 0o600

    fd = os.open(self.config_path, flags, mode)
    with os.fdopen(fd, 'w') as f:
        yaml.dump(self.data, f)

```

This approach eliminates the temporary window where a newly created file might inherit default permissions (potentially world-readable) before explicit restrictions are applied.

### Cross-Platform Fallback Handling

On Windows or environments where `os.open` flags are unavailable, Agent-Reach implements a fallback mechanism. Lines 66-73 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) catch exceptions and use the standard `open` call followed by explicit `os.chmod` to force `0o600` permissions:

```python
try:
    # Primary atomic method

    fd = os.open(self.config_path, flags, mode)
except (OSError, AttributeError):
    # Fallback for Windows or restricted environments

    with open(self.config_path, 'w') as f:
        yaml.dump(self.data, f)
    os.chmod(self.config_path, 0o600)

```

Note that on Windows, `os.chmod` is effectively a no-op for ACL-based permissions, so the code relies on the operating system's default file creation semantics while maintaining API compatibility.

## Runtime Protection and Secret Masking

Beyond filesystem permissions, Agent-Reach protects against accidental credential exposure in logs and console output. The `to_dict` method (lines 108-127 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) automatically masks sensitive values based on key name patterns.

The masking logic identifies keys containing substrings like "key", "token", "password", or "cookie", replacing their values with truncated placeholders:

```python
def to_dict(self):
    sensitive = ['key', 'token', 'password', 'cookie', 'secret']
    result = {}
    for k, v in self.data.items():
        if any(marker in k.lower() for marker in sensitive):
            result[k] = str(v)[:8] + '...'  # Truncate after 8 chars

        else:
            result[k] = v
    return result

```

This ensures that calling `print(config.to_dict())` or logging the configuration object never exposes full credential values, even if the output is redirected to shared logs or bug reports.

## Verification and Best Practices

You can verify these security measures on POSIX systems using standard command-line tools:

```bash

# Check directory permissions (should show drwx------)

ls -ld ~/.agent-reach

# Check file permissions (should show -rw-------)

ls -l ~/.agent-reach/config.yaml

```

Expected output:

```

drwx------ 2 user user 4096 Jan 15 09:00 /home/user/.agent-reach
-rw------- 1 user user  220 Jan 15 09:00 /home/user/.agent-reach/config.yaml

```

When implementing Agent-Reach in production environments:

- **Avoid cloud syncing** the `~/.agent-reach` directory to prevent credential proliferation across devices
- **Audit umask settings** to ensure system-wide defaults don't override these restrictions
- **Use environment variables** for credentials when feasible, as `Config.get()` checks environment variables before falling back to the file
- **Regularly rotate** API keys stored in the configuration file

## Summary

- **Agent-Reach stores sensitive data** in `~/.agent-reach/config.yaml` and enforces **directory permissions `0o700`** via `make_private_dir` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py)
- **File creation uses atomic `os.open`** with `stat.S_IRUSR | stat.S_IWUSR` (`0o600`) in `Config.save` to prevent race condition vulnerabilities
- **Windows fallback** uses standard file operations with subsequent `os.chmod` calls, though Windows ACLs depend on OS defaults
- **Runtime masking** via `to_dict` prevents accidental credential leakage in logs by truncating values for keys matching sensitive patterns
- **Verification** on POSIX systems shows `drwx------` for the directory and `-rw-------` for the configuration file

## Frequently Asked Questions

### What permissions does Agent-Reach set on its configuration directory?

Agent-Reach creates the configuration directory at `~/.agent-reach` with mode `0o700` (owner read, write, and execute only) through the `make_private_dir` function in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py). This prevents other users from listing or accessing directory contents on POSIX systems.

### How does Agent-Reach prevent temporary file exposure during writes?

The `Config.save` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) uses `os.open` with the flags `stat.S_IRUSR | stat.S_IWUSR` (octal `0o600`) to atomically create the file with restricted permissions. This eliminates the race window where a file might temporarily exist with default permissions before explicit restrictions are applied.

### Does Agent-Reach protect credentials when printing configuration objects?

Yes, the `to_dict` method automatically masks values for keys containing "key", "token", "password", or "cookie", displaying only the first eight characters followed by ellipsis. This prevents accidental exposure of secrets in logs, stack traces, or debug output.

### Are these security measures effective on Windows?

Partially. While the code attempts to set `0o600` permissions via `os.chmod`, Windows uses ACL-based security rather than POSIX modes, making `os.chmod` a no-op. On Windows, Agent-Reach relies on the operating system's default file creation semantics and the user's home directory protections, though the masking and directory creation logic still function correctly.