How Agent Reach's Home Isolation Feature Protects User Directories

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 at line 10, where the isolated_home fixture establishes the sandbox:

# 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 (line 101) uses standard Path.home() calls, which naturally resolve to the sandboxed location when the environment variables are set:

# 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:

# 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 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 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:

# 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
• The mechanism protects real user directories from test overwrites, credential leakage, and configuration pollution
• All components—from agent_reach/config.py to channel implementations—transparently respect the sandbox through standard library path resolution
• Automated tests in 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.

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