# How to Migrate Agent Reach Configuration Between Different Machines

> Easily migrate Agent Reach configuration between machines. Copy your config.yaml file and verify the setup with a simple command. Ensure a smooth transition for your agent reach deployment.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:
   ```bash
   cp ~/.agent-reach/config.yaml /tmp/agent-reach-config.yaml
   ```

2. **Transfer the file** using any secure method (scp, rsync, or encrypted storage):
   ```bash
   scp /tmp/agent-reach-config.yaml user@newhost:~/.
   ```

3. **Import on the destination** by placing the file in the correct location with proper permissions:
   ```bash
   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:
   ```bash
   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.

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), lines 997-1012):

```bash

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