# Local vs Server Environment Modes in Agent Reach: Key Differences Explained

> Understand the key differences between Agent Reach local and server environment modes. Learn how each mode impacts installation and operation for your specific needs.

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

---

**Agent Reach operates in two distinct runtime contexts—local mode for graphical workstations with browsers, and server mode for headless VMs and containers—determining whether the installer extracts browser cookies, prompts for interactive input, or skips UI-dependent steps.**

Agent Reach, an open-source automation framework maintained at `Panniantong/Agent-Reach`, adapts its installation behavior based on whether it detects a local workstation or a remote server environment. The `--env` flag and the `_detect_environment()` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) control critical differences in how the CLI handles authentication, user interaction, and network security warnings.

## How Agent Reach Detects Your Environment

The CLI defines the `--env` argument with three choices: `local`, `server`, or `auto`. This configuration appears in the argument parser at lines 63-66 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

### The Auto-Detection Algorithm

When `--env auto` is selected (or omitted), the `_detect_environment()` function (lines 975-1014) executes heuristics to determine the runtime context. According to the source code, this function examines **SSH variables**, **Docker markers**, **display variables**, and **cloud-hypervisor clues** to distinguish between personal workstations and headless infrastructure. The function returns `"local"` for graphical sessions with desktop environments and `"server"` for SSH connections, VPS instances, or containerized environments.

### Manual Mode Selection

You can override auto-detection by explicitly passing the environment flag:

```bash

# Force local mode on a laptop with browser access

agent-reach install --env local --channels twitter,bilibili

# Force server mode on a headless VM or Docker container

agent-reach install --env server --channels reddit,linkedin

```

## Feature Differences Between Local and Server Modes

The selected mode drives conditional branches throughout the installation process, particularly around **cookie management**, **user interaction**, and **security advisories**.

### Browser Cookie Extraction (Local Mode Only)

In local mode, the installer attempts to read authentication cookies directly from Chrome or Firefox when channels like Twitter, Xueqiu, or Bilibili are requested. The `configure_from_browser` logic (lines 52-58) executes only when `env == "local"`, triggering the browser's native credential store. On macOS, this may prompt for **Keychain access** requiring user interaction.

Server mode skips the cookie import phase entirely (see the conditional block at lines 252-274), as headless servers typically lack browser installations.

### Interactive vs Silent Installation

Local mode assumes a graphical session with a logged-in user, allowing the installer to display interactive messages and pause for input. Server mode assumes a **non-interactive environment** and performs silent installations, avoiding any action that requires a display or user-level keychain access.

### Network and Security Advisories

Server mode activates specific warnings about IP-based blocking. The source code at lines 81-88 prints server-specific advice, such as warnings that **Bilibili may block server IPs** and recommendations to install residential proxies. Local mode assumes residential IP addresses and suppresses these warnings, instead displaying system-wide advice relevant to desktop users.

## Code Implementation and Usage Examples

The environment variable is stored in the `env` variable and checked throughout the installer logic. When `auto` detection is used, the CLI prints the determined environment:

```python
if env == "server":
    print("Environment: Server/VPS (auto-detected)")
else:
    print("Environment: Local computer (auto-detected)")

```

The cookie import block specifically guards against server execution:

```python
if env == "local" and needs_cookies and not safe_mode and not dry_run:
    # import cookies from browsers …

```

For automated deployments, use the auto-detection (recommended) or explicitly set server mode:

```bash

# Auto-detect (recommended for most use cases)

agent-reach install --env auto

# Typical server deployment with specific channels

agent-reach install --env server --channels linkedin,reddit

```

## Summary

- **Local mode** targets personal workstations with graphical sessions and browsers, enabling automatic cookie extraction from Chrome/Firefox and allowing interactive prompts.
- **Server mode** targets headless VMs, VPS instances, and Docker containers, skipping cookie imports and UI-dependent steps while displaying IP-blocking warnings.
- **Auto-detection** via `_detect_environment()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 975-1014) examines SSH variables, Docker markers, and display variables to determine the appropriate mode.
- The `--env` flag accepts `local`, `server`, or `auto` to control these behaviors explicitly during installation.

## Frequently Asked Questions

### How does Agent Reach automatically detect if I'm running on a server?

Agent Reach uses the `_detect_environment()` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 975-1014) to scan for SSH connection variables, Docker container markers, missing display variables, and cloud-hypervisor indicators. If any of these server-specific signals are present, the function returns `"server"`; otherwise, it defaults to `"local"`.

### Why does Agent Reach ask for my macOS Keychain password in local mode?

When running in local mode with channels requiring authentication (like Twitter or Bilibili), Agent Reach calls `configure_from_browser` to extract stored cookies from Chrome or Firefox. On macOS, this requires accessing the system Keychain to decrypt browser credentials, triggering the password prompt. This behavior is bypassed entirely in server mode.

### Can I install Agent Reach on a Docker container without browser support?

Yes. Use `--env server` when installing in a Docker container or any headless environment. This forces the installer to skip the browser cookie import phase and avoid interactive prompts, completing a silent installation suitable for containerized deployments.

### What happens if I force local mode on a headless server?

If you specify `--env local` on a headless server, Agent Reach will attempt to execute browser-based cookie extraction and may hang waiting for interactive input that never arrives. The installer assumes a graphical session exists, so cookie-dependent channel installations will fail unless you manually provide credentials through other means.