# How to Manage Multiple Platform Credentials Securely in ~/.agent-reach/

> Securely manage multiple platform credentials in ~/.agent-reach/ with Agent Reach. This guide explains unified Config class for safe read/write, env variable fallbacks, and credential masking.

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

---

**Agent Reach stores all platform-specific secrets in `~/.agent-reach/config.yaml` with 600 file permissions and provides a unified `Config` class to handle secure read/write operations, environment variable fallbacks, and automatic credential masking.**

The open-source **Agent Reach** repository ([Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach)) provides a centralized mechanism for handling API keys, OAuth tokens, and cookies across multiple platforms. By leveraging the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), you can manage multiple platform credentials securely in `~/.agent-reach/` without exposing sensitive data to other system users or process logs.

## Secure Storage Architecture in ~/.agent-reach/

The framework implements defense-in-depth for credential storage through strict filesystem permissions and atomic write operations.

### Automatic Directory Creation

On first initialization, Agent Reach automatically creates the configuration directory at `~/.agent-reach` if it does not exist. The `CONFIG_DIR` constant in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) defines this path using `Path.home() / ".agent-reach"`, ensuring cross-platform compatibility while maintaining a consistent location for all secret storage.

### File Permission Hardening (0o600)

When writing credentials to disk, the `Config` class enforces restrictive file permissions using `os.open` with `stat.S_IRUSR | stat.S_IWUSR`:

```python

# From agent_reach/config.py - writes with 600 permissions

os.open(path, flags, stat.S_IRUSR | stat.S_IWUSR)

```

This creates files with mode `0o600` (read/write for owner only), preventing group members or other users from accessing your Twitter tokens, GitHub API keys, or Reddit credentials even if they have system access.

## Using the Config Class for Credential Management

All interactions with `~/.agent-reach/config.yaml` flow through the `Config` class, providing a consistent interface for secure credential handling.

### Loading and Initializing the Configuration

Instantiate the `Config` class to load existing credentials or initialize a new empty configuration:

```python
from agent_reach.config import Config

# Loads existing config or creates empty config.yaml at ~/.agent-reach/

cfg = Config()

```

### Storing Platform Credentials Securely

Use the `set()` method to persist credentials with automatic permission enforcement:

```python

# Store Twitter XReach tokens - file automatically saved with 600 permissions

cfg.set("twitter_auth_token", "YOUR_TWITTER_AUTH_TOKEN")
cfg.set("twitter_ct0", "YOUR_TWITTER_CT0")

# Store GitHub token for increased API rate limits

cfg.set("github_token", "ghp_xxxxxxxxxxxx")

```

Each call to `set()` triggers an atomic write operation that preserves the `0o600` permission mask, ensuring your secrets remain inaccessible to other system users.

### Retrieving Credentials with Environment Fallback

The `get()` method implements a secure lookup chain that prioritizes the YAML file while allowing environment variable overrides:

```python

# Checks ~/.agent-reach/config.yaml first, then GITHUB_TOKEN env var

token = cfg.get("github_token")

# Returns None if not found in either location

```

This pattern allows temporary credential overrides without persisting secrets to disk—ideal for CI/CD pipelines or temporary access tokens.

## Feature-Aware Configuration Validation

Agent Reach maps platform integrations to required credential sets via the `FEATURE_REQUIREMENTS` dictionary in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). Each feature (like `"twitter_xreach"` or `"reddit_reach"`) specifies a list of required secret keys.

Verify complete platform configuration using `is_configured()`:

```python
if cfg.is_configured("twitter_xreach"):
    print("Twitter XReach ready - all required tokens present")
else:
    print("Missing required Twitter credentials")

```

This method checks that all keys defined in the feature requirements exist and contain non-empty values, preventing runtime authentication failures.

## Masking Sensitive Values for Safe Logging

When displaying configuration data or debugging, the `to_dict()` method automatically masks sensitive values to prevent accidental credential leakage:

```python
print(cfg.to_dict())

# Output: {'twitter_auth_token': 'abcd1234...', 'github_token': 'ghp_xxxx...'}

```

Any configuration key containing `"key"`, `"token"`, `"password"`, or `"proxy"` is truncated to its first eight characters followed by an ellipsis. This safety mechanism protects your secrets when sharing logs or UI output.

## Interactive CLI Configuration

The command-line interface in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) provides an interactive install wizard that securely captures credentials:

```python

# Excerpt from agent_reach/cli.py install wizard

print("【可选】GitHub Token — 提高 API 限额")
current = config.get("github_token")
if not current:
    key = input("  GITHUB_TOKEN (回车跳过): ").strip()
    if key:
        config.set("github_token", key)

```

Run `agent-reach install` to trigger this guided setup, which prompts for each platform's required credentials and validates them via `config.is_configured()` before marking the feature as ready.

## Summary

- **Agent Reach** consolidates all platform secrets in `~/.agent-reach/config.yaml` with automatic `0o600` permission enforcement.
- The **`Config`** class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles secure storage, retrieval, and validation of credentials.
- **Environment variable fallback** allows temporary overrides without persisting sensitive data to disk.
- **Feature requirements mapping** ensures all necessary credentials are present before enabling platform integrations.
- **Automatic masking** in `to_dict()` prevents credential leakage in logs by truncating sensitive values.
- The **CLI install wizard** provides an interactive interface for initial configuration without manual file editing.

## Frequently Asked Questions

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

Agent Reach creates `~/.agent-reach/config.yaml` with mode `0o600` (read/write owner only) using `os.open` with `stat.S_IRUSR | stat.S_IWUSR` flags. This prevents other system users from reading your API keys even if they have filesystem access.

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

Yes. The `Config.get()` method checks `~/.agent-reach/config.yaml` first, then falls back to uppercase environment variables (e.g., `GITHUB_TOKEN`). This allows you to override credentials temporarily without writing them to disk.

### How do I know if I've configured all required credentials for a platform?

Call `cfg.is_configured("feature_name")` where `feature_name` corresponds to keys in `FEATURE_REQUIREMENTS` (e.g., `"twitter_xreach"`, `"reddit_reach"`). This returns `True` only if all required credential keys for that platform exist and contain values.

### Is it safe to print the Config object for debugging?

Yes, but use `cfg.to_dict()` rather than accessing the raw dictionary. The `to_dict()` method automatically masks any values where the key contains `"key"`, `"token"`, `"password"`, or `"proxy"`, showing only the first eight characters followed by an ellipsis to prevent accidental credential exposure.