How to Migrate Agent Reach Configuration Between Different Machines

To migrate Agent Reach configuration, copy the ~/.agent-reach/config.yaml file from the source machine to the same location on the destination machine and verify with python -m agent_reach.cli doctor.

Agent Reach stores all user-specific settings—including API keys, proxy definitions, and platform-specific cookies—in a single YAML file. Because the configuration is stored as plain text in the user's home directory, migrating Agent Reach configuration between machines requires only copying this file and ensuring proper permissions. The Config class in agent_reach/config.py handles the directory creation, atomic file writes, and environment variable fallbacks that make this migration straightforward.

Where Agent Reach Stores Configuration Data

Agent Reach persists all settings in a single file located at ~/.agent-reach/config.yaml. According to the source code in agent_reach/config.py (lines 15-20), the Config class defines this path through a hard-coded directory name and filename:

• Directory: ~/.agent-reach (created automatically if missing via _ensure_dir)
• Filename: config.yaml

When the Config object is instantiated, it automatically creates the directory if it does not exist and loads any existing YAML content. The save method (lines 50-60) uses an atomic os.open call with mode 0o600, ensuring the file is only readable by the owner. This security-conscious approach means you must preserve these permissions during migration to prevent unauthorized access to sensitive credentials like twitter_auth_token, groq_api_key, or proxy passwords.

Step-by-Step Migration Workflow

Follow these steps to migrate your configuration securely:

1. Export the source configuration from the original host:

   cp ~/.agent-reach/config.yaml /tmp/agent-reach-config.yaml

2. Transfer the file using any secure method (scp, rsync, or encrypted storage):

   scp /tmp/agent-reach-config.yaml user@newhost:~/.

3. Import on the destination by placing the file in the correct location with proper permissions:

   mkdir -p ~/.agent-reach
   mv ~/agent-reach-config.yaml ~/.agent-reach/config.yaml
   chmod 600 ~/.agent-reach/config.yaml

4. Validate the migration using the built-in diagnostics command. The doctor command loads the configuration via the same Config class and checks each optional feature's requirements:

   python -m agent_reach.cli doctor

Programmatic Migration Using the Config Class

For automation or backup scripts, you can use the Config class directly to export and import settings. The Config.get method (lines 69-78) first checks the in-memory dictionary, then falls back to environment variables (uppercase keys), allowing flexible deployment scenarios.

from pathlib import Path
from agent_reach.config import Config
import shutil
import os
import stat
import yaml

# Export: serialize current config to a portable dict

cfg = Config()
export_path = Path("/tmp/agent-reach-export.yaml")
fd = os.open(
    export_path, 
    os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 
    stat.S_IRUSR | stat.S_IWUSR
)
with os.fdopen(fd, "w", encoding="utf-8") as f:
    yaml.dump(cfg.data, f, default_flow_style=False, allow_unicode=True)

# Import on another machine

target = Path.home() / ".agent-reach" / "config.yaml"
target.parent.mkdir(parents=True, exist_ok=True)
shutil.move(str(export_path), str(target))
os.chmod(target, 0o600)  # enforce private permissions

Alternative: CLI-Based Configuration Recreation

If you prefer not to copy the raw YAML file, you can recreate the same settings using the configure sub-command. The CLI parses arguments and writes them using Config.set (implemented in agent_reach/cli.py, lines 997-1012):

# Re-apply proxy settings

python -m agent_reach.cli configure proxy http://user:pass@proxy.example.com:8080

# Re-apply API tokens

python -m agent_reach.cli configure github-token ghp_XXXXXXXXXXXXXXXXXXXX

This approach is useful when migrating selective configurations or when the raw YAML contains obsolete entries you wish to exclude.

Handling Edge Cases and Permissions

When migrating Agent Reach configuration, consider these specific scenarios:

• Different OS user: Ensure the target user owns ~/.agent-reach/config.yaml. The chmod 600 command restricts access to the file owner only, preventing other users on the system from reading API keys.

• Missing optional dependencies: Run agent-reach install on the new machine to reinstall required tools (e.g., twitter-cli, mcporter) that the configuration references but are not stored in the YAML file.

• Docker-based back-ends: For platforms like XiaoHongShu MCP, the configuration file stores only the cookie JSON; the Docker container must still be running on the new host. Use python -m agent_reach.cli doctor to verify container status after migration.

• Environment-variable overrides: If you rely on environment variables rather than the YAML file, export them on the destination (export GITHUB_TOKEN=...). The CLI will pick them up automatically via the Config.get fallback mechanism.

Summary

• Agent Reach stores all configuration in ~/.agent-reach/config.yaml as a YAML file with restricted permissions (0o600).
• Migration requires copying this single file to the new machine's home directory and ensuring the same permissions.
• Validate migrated configurations using python -m agent_reach.cli doctor, which checks feature requirements and container status.
• The Config class supports environment variable fallbacks, allowing hybrid migration strategies where sensitive keys are injected via env vars rather than the YAML file.
• For selective migrations, use the configure sub-command in agent_reach/cli.py to recreate specific settings without transferring the entire configuration file.

Frequently Asked Questions

Where is the Agent Reach configuration file located?

Agent Reach stores its configuration in ~/.agent-reach/config.yaml within the user's home directory. This location is hard-coded in the Config class in agent_reach/config.py (lines 15-20) and is created automatically when the application first runs.

Does Agent Reach support environment variables for configuration?

Yes. The Config.get method (lines 69-78) checks the in-memory configuration dictionary first, then falls back to environment variables using uppercase key names. This allows you to override YAML settings by exporting variables like GITHUB_TOKEN or GROQ_API_KEY in your shell.

How do I verify my migrated configuration is working?

Run the built-in diagnostic command python -m agent_reach.cli doctor. This command loads the configuration via the Config class and checks each optional feature's requirements, reporting any missing keys or connectivity issues. It also verifies Docker container status for back-ends like XiaoHongShu MCP.

Can I migrate configuration between different operating systems?

Yes. Because the configuration file is plain YAML containing key-value pairs (such as twitter_auth_token and proxy URLs), it is platform-agnostic. Simply copy the file to the appropriate location on the target system (~/.agent-reach/config.yaml on Linux/macOS or %USERPROFILE%\.agent-reach\config.yaml on Windows) and ensure the file permissions are restricted to the owner.

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