# How Agent Reach's Home Isolation Feature Protects User Directories

> Discover Agent Reach's home isolation feature. Learn how it creates a sandboxed directory to protect user credentials and configurations from accidental overwrites during CLI operations and tests.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: security
- Published: 2026-08-05

---

**Agent Reach's home isolation feature creates a sandboxed temporary home directory that redirects all `Path.home()` calls away from real user files, preventing accidental overwrites of credentials and configurations during CLI operations and test runs.**

This **home isolation** mechanism is central to Agent Reach's safety model. Instead of operating directly in a user's actual `$HOME` directory, the framework intercepts environment variables and forces all path resolution through an isolated temporary folder. This protects sensitive files like `~/.agent-reach/config.json` and third-party credential stores while ensuring clean, repeatable test execution.

## Where Home Isolation Is Implemented

The core isolation logic lives in **[`tests/conftest.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/conftest.py)** at line 10, where the `isolated_home` fixture establishes the sandbox:

```python

# tests/conftest.py - the isolated_home fixture

@pytest.fixture
def isolated_home(tmp_path, monkeypatch):
    """Create a temporary home directory and redirect all home-related env vars."""
    home = tmp_path / "home"
    home.mkdir()
    
    # Redirect all platform-specific home variables

    monkeypatch.setenv("HOME", str(home))
    monkeypatch.setenv("USERPROFILE", str(home))
    monkeypatch.setenv("XDG_CONFIG_HOME", str(home / ".config"))
    monkeypatch.setenv("APPDATA", str(home / "AppData" / "Roaming"))
    monkeypatch.setenv("LOCALAPPDATA", str(home / "AppData" / "Local"))
    
    return home

```

This fixture is automatically applied to tests that need directory isolation, ensuring no test can touch real user data.

## How Path Resolution Is Redirected

Agent Reach's configuration system in **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** (line 101) uses standard `Path.home()` calls, which naturally resolve to the sandboxed location when the environment variables are set:

```python

# agent_reach/config.py - configuration directory resolution

from pathlib import Path

class Config:
    """Central configuration management for Agent Reach."""
    
    CONFIG_DIR = Path.home() / ".agent-reach"
    CONFIG_FILE = CONFIG_DIR / "config.json"
    
    @classmethod
    def ensure_config_dir(cls):
        cls.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
        return cls.CONFIG_DIR

```

Because `Path.home()` respects the `HOME` environment variable on Unix and `USERPROFILE` on Windows, the isolation is transparent to all code using standard path utilities.

## Validation Through Automated Testing

The test suite enforces isolation guarantees in **[`tests/test_home_isolation.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_home_isolation.py)**:

```python

# tests/test_home_isolation.py - verifying sandbox containment

import os
from pathlib import Path
from agent_reach.config import Config

def test_runtime_home_and_config_are_inside_test_sandbox(isolated_home):
    # All home resolution methods must point to sandbox

    assert Path.home() == isolated_home
    assert Path(os.path.expanduser("~")) == isolated_home
    
    # All config paths must be under sandbox

    assert Config.CONFIG_DIR.is_relative_to(isolated_home)
    assert Config.CONFIG_FILE.is_relative_to(isolated_home)
    
    # Verify no leakage to real home

    real_home = Path(os.environ.get("HOME", "/tmp")).resolve()
    assert not str(Config.CONFIG_DIR).startswith(str(real_home))

```

This test runs on every CI build, catching any regression that might escape the sandbox.

## Real-World Protection Scenarios

### Protecting Credential Files

Channel implementations that integrate with third-party services (Reddit, XiaoHongShu, RDT-CLI) read credential files from standard locations. The **[`tests/test_reddit_channel.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_reddit_channel.py)** suite validates that these lookups stay within the isolated home:

- **`~/.config/rdt-cli/credential.json`** → resolves to `<sandbox>/.config/rdt-cli/credential.json`
- **`~/.agent-reach/channel_configs/reddit.json`** → resolves under sandbox root

Even if a test case attempts to write malformed credentials, the real `~/.config` remains untouched.

### Doctor Command Safety

The diagnostic **`doctor`** command in **[`tests/test_doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_doctor.py)** performs system health checks that may create temporary files or probe configuration directories. Running through `isolated_home` ensures:

1. Diagnostic artifacts are cleaned up automatically with the temp folder
2. No persistent state leaks between test runs
3. CI environments remain pristine

## Manual Isolation for Development

Developers can manually enter the same sandbox mode for debugging:

```python

# Manual sandbox entry (replicates the test fixture logic)

import os
import tempfile
from pathlib import Path

def enter_sandbox():
    """Redirect home to a temporary directory for safe testing."""
    sandbox = Path(tempfile.mkdtemp(prefix="agent-reach-"))
    home_dir = sandbox / "home"
    home_dir.mkdir(parents=True)
    
    # Set all platform variables

    os.environ["HOME"] = str(home_dir)
    os.environ["USERPROFILE"] = str(home_dir)
    os.environ["XDG_CONFIG_HOME"] = str(home_dir / ".config")
    os.environ["APPDATA"] = str(home_dir / "AppData" / "Roaming")
    os.environ["LOCALAPPDATA"] = str(home_dir / "AppData" / "Local")
    
    # Verify isolation took effect

    assert Path.home() == home_dir, "Sandbox activation failed"
    return home_dir

# Usage

with tempfile.TemporaryDirectory() as tmp:
    sandbox_home = enter_sandbox()
    # All Agent Reach operations now confined to sandbox

    from agent_reach.config import Config
    print(f"Safe config dir: {Config.CONFIG_DIR}")

```

## Platform Coverage

The isolation covers all major platforms through environment variable coverage:

| Platform | Variable | Used By |
|----------|----------|---------|
| Linux/macOS | `HOME` | `Path.home()`, shell expansion |
| Linux/macOS | `XDG_CONFIG_HOME` | Freedesktop-compliant tools |
| Windows | `USERPROFILE` | `Path.home()` fallback |
| Windows | `APPDATA` | Roaming application data |
| Windows | `LOCALAPPDATA` | Local application data |

This comprehensive coverage ensures consistent behavior across CI runners (GitHub Actions, GitLab CI, local Docker) regardless of host OS.

## Summary

- **Home isolation** in Agent Reach redirects `Path.home()` calls to a temporary sandbox via environment variable manipulation in [`tests/conftest.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/conftest.py)
- The mechanism protects real user directories from test overwrites, credential leakage, and configuration pollution
- All components—from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to channel implementations—transparently respect the sandbox through standard library path resolution
- Automated tests in [`tests/test_home_isolation.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_home_isolation.py) enforce containment guarantees on every build

## Frequently Asked Questions

### What happens if the HOME environment variable is already set when running tests?

The `isolated_home` fixture uses `monkeypatch.setenv`, which temporarily overrides any existing value for the duration of the test. After the test completes, the original environment is automatically restored, ensuring no persistent changes to the developer's shell environment.

### Does home isolation affect production CLI usage?

No. Production CLI runs use the real home directory unless explicitly sandboxed. The isolation is primarily a test-time safety mechanism, though developers can manually activate it for debugging risky operations using the pattern shown in the manual sandbox example.

### How does Agent Reach handle third-party tools that cache credentials in non-standard locations?

The fixture covers the most common credential paths through `XDG_CONFIG_HOME`, `APPDATA`, and `LOCALAPPDATA`. Tools using hardcoded paths outside these conventions may require additional monkeypatching in specific test cases, as seen in the Reddit channel tests.