# Local vs Server Environment in Agent-Reach: Deployment and Installation Differences

> Understand Agent-Reach deployment and installation differences between local workstation and headless server environments. Agent-Reach auto-detects, but you can force mode with --env flag.

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

---

**Agent-Reach automatically detects whether it is running on a local workstation or headless server and adjusts dependency installation, channel selection, and authentication methods accordingly, though you can force a specific mode using the `--env` flag.**

The Panniantong/Agent-Reach framework supports dual deployment models, allowing seamless operation on both developer laptops and cloud infrastructure. Understanding the **local vs server environment** differences ensures you select the correct toolchain and authentication strategy for your deployment target. The CLI handles most decisions automatically through environment detection, but explicit control via command-line flags provides predictable behavior across CI/CD pipelines and containerized workflows.

## Automatic Environment Detection

Agent-Reach determines the deployment context through the `_detect_environment()` function implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 555–594).

The detector evaluates multiple "server" signals:

- Active SSH sessions
- Presence of Docker or OCI container files
- Missing display environment variables (`DISPLAY`)
- Cloud-VM identifier files
- Results from `systemd-detect-virt`

When two or more of these indicators are present, the function returns `"server"`; otherwise, it defaults to `"local"`. This detection occurs automatically during the `install` command, but you can override it explicitly with the `--env` parameter.

## Installation Behavior Differences

### Channel Selection and Tooling

The installer chooses different channel implementations based on the environment flag, as seen in the conditional logic around lines 222–302 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

**Local environment** deployments receive desktop-oriented tools:

- **Reddit**: Configured with the `rdt-cli` client
- **YouTube**: Uses `yt-dlp` with browser-extracted cookies
- **GUI-dependent channels**: Enabled and configured automatically

**Server environment** deployments switch to headless-compatible alternatives:

- **Reddit**: Uses the `opencli` client (a headless-compatible wrapper)
- **YouTube**: Operates without browser-dependent cookie extraction
- **GUI channels**: Skipped entirely during installation

### Dependency Installation and Safe Mode

Local installations proceed with automatic dependency resolution, installing GUI-related runtimes like `node` for `mcporter` or browser automation libraries.

Server installations operate differently. When `env == "server"` or when you pass the `--safe` flag, the CLI enters safe-mode and prints installation instructions rather than executing them directly. This prevents failures on headless systems that lack the required display libraries or browser runtimes.

### Cookie Extraction and Authentication

Authentication workflows diverge significantly between environments.

On **local workstations**, the `configure` command can automatically scrape cookies from installed browsers (`chrome`, `firefox`, etc.) because it can access your user profile and display.

On **servers**, cookie extraction is disabled entirely. You must supply authentication cookies manually via the `configure` sub-command using file imports or environment variables, as implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

### Network Proxy Handling

Both environments store proxy settings in the configuration, but the application differs:

- **Local**: The CLI writes proxy settings to the config and forwards them to desktop browsers and tools like Reddit/Twitter clients
- **Server**: The CLI emits `export` commands for shell configuration but skips browser-specific proxy settings, as referenced in the legacy `bilibili_proxy` key handling

## How to Force a Specific Environment

While automatic detection covers most use cases, explicit flags ensure consistent behavior across CI runners and containers.

Install on a local workstation (auto-detect):

```bash
python -m agent_reach.cli install

```

Force local mode explicitly:

```bash
python -m agent_reach.cli install --env=local

```

Install on a headless server:

```bash
python -m agent_reach.cli install --env=server

```

Preview server installation without system changes (safe-mode):

```bash
python -m agent_reach.cli install --env=server --safe

```

## Diagnostic Output Variations

The [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) module adjusts health checks based on the environment flag passed to the CLI.

**Local diagnostics** include GUI-dependent checks such as X server availability and browser profile accessibility.

**Server diagnostics** trim the output to relevant headless checks, suppressing display-related warnings and skipping GUI tool verification. This ensures the `doctor` command provides actionable insights without false positives about missing desktop dependencies.

The unit tests in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) verify this branching behavior, specifically in `test_install_reddit_deps_routes_by_environment`, which validates that Reddit dependency routes correctly select between `rdt-cli` and `opencli` based on the detected environment.

## Summary

- **Automatic detection** in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 555–594) analyzes SSH sessions, Docker containers, and display variables to determine the deployment context
- **Channel selection** switches between desktop clients (`rdt-cli`) and headless wrappers (`opencli`) depending on the environment
- **Safe-mode** (`--safe` flag) on servers prints installation instructions rather than executing system changes
- **Cookie extraction** requires manual configuration on servers, while local workstations support automatic browser scraping
- **Diagnostic checks** in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) adapt to suppress irrelevant GUI warnings on headless hosts

## Frequently Asked Questions

### How does Agent-Reach determine if I am running on a server or local workstation?

The framework executes the `_detect_environment()` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), which checks for server indicators including active SSH sessions, Docker/OCI container files, missing `DISPLAY` variables, cloud-VM identifiers, and virtualization status via `systemd-detect-virt`. When two or more indicators are present, it classifies the system as a server environment.

### What is the difference between `rdt-cli` and `opencli` for Reddit integration?

`rdt-cli` is the desktop-oriented client installed for local environments, requiring Node.js and browser capabilities. `opencli` is the headless-compatible wrapper selected for server environments that operates without GUI dependencies. The installer routes to the appropriate client based on the `env` flag around lines 222–302 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

### Why does cookie extraction fail during configuration on my CI runner?

Server environments disable automatic cookie extraction because they lack browser profiles and display capabilities. According to the implementation in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), you must manually supply cookies via the `configure` command on headless systems, whereas local workstations can scrape directly from Chrome or Firefox profiles.

### Can I test the installation steps without modifying my server?

Yes. Append the `--safe` flag to your install command when using `--env=server`. This activates safe-mode, causing the CLI to print the installation instructions and dependency requirements without executing system changes, allowing you to review the steps before applying them manually.