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

Agent Reach distinguishes between local mode to enable browser cookie extraction and interactive prompts on workstations, and server mode to disable UI-dependent steps for headless VPS and container deployments.

The Panniantong/Agent-Reach CLI supports two distinct runtime contexts that fundamentally change how the installation process behaves. Understanding the difference between local and server environment modes ensures you configure the tool correctly whether you are running it on a personal laptop or deploying it to remote infrastructure.

How Environment Modes Are Defined

The environment mode is controlled via the --env argument defined in agent_reach/cli.py at lines 63-66, which accepts three values: local, server, or auto. When you select auto, the installer invokes the _detect_environment() function (lines 975-1014) to heuristically determine the context by examining SSH variables, Docker markers, display variables, and cloud-hypervisor clues.

The detection logic categorizes your system as either a personal workstation with a graphical session or a headless infrastructure target such as a VPS, Docker container, or remote VM accessed via SSH.

Critical Differences Between Local and Server Modes

Browser Cookie Extraction

In local mode, when installing channels that require authentication (such as Twitter, Xueqiu, or Bilibili), the installer automatically attempts to read cookies from your local Chrome or Firefox browser via the configure_from_browser function (lines 52-58). This process may trigger a macOS Keychain password prompt or similar authentication dialogs.

Server mode skips the cookie import phase entirely (as implemented in the conditional block at lines 252-274) because headless servers typically lack browser installations and cannot access user-level keychains.

User Interaction Requirements

Local mode assumes the presence of a display server and may pause execution for interactive steps, such as requesting sudo privileges or displaying GUI prompts. Server mode assumes a non-interactive environment and performs only silent installations, avoiding any action that requires a display or user-level keychain access.

System-Wide Safety Assumptions

The local environment assumes it can safely run user-level package managers and modify user files without strict isolation. Conversely, server mode assumes a restricted environment where the installer must avoid actions requiring graphical session access or elevated interactive permissions.

Platform-Specific Advice

When running in server mode, the CLI displays specific warnings in agent_reach/cli.py (lines 81-88) regarding IP blocking issues—such as Bilibili potentially blocking server IP addresses—and recommends installing residential proxies. Local mode provides different guidance suitable for residential networks.

Specifying Your Environment Mode

You can explicitly set the mode during installation or allow automatic detection:

# Auto-detect based on system indicators (recommended)

agent-reach install --env auto

# Force local mode for workstations with browser access

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

# Force server mode for headless VMs or Docker containers

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

When using --env local with cookie-dependent channels, the installer executes the _cmd_install flow to import browser credentials. When using --env server, the installer bypasses cookie imports and prints server-specific configuration hints instead.

Implementation in the Source Code

The environment-specific behavior branches are located in agent_reach/cli.py:

• Argument definition: Lines 63-66 define the --env choices
• Auto-detection logic: Lines 975-1014 contain the _detect_environment() implementation
• Conditional execution: Lines 252-274 handle the environment printout and cookie import gating
• Server warnings: Lines 81-88 provide server-specific advice about proxy requirements

The core conditional logic that governs cookie extraction appears as:

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

Summary

• Local mode targets personal workstations with graphical sessions and browsers, enabling automatic cookie extraction and interactive installation steps.
• Server mode targets headless VMs, VPS instances, and Docker containers, skipping browser-dependent actions and providing infrastructure-specific advice.
• Auto-detection examines SSH variables, Docker markers, and display context via _detect_environment() to select the appropriate mode.
• The environment setting directly controls cookie import logic in agent_reach/cli.py (lines 252-274) and determines whether UI prompts or silent operation occurs.

Frequently Asked Questions

How does Agent Reach automatically detect server environments?

The _detect_environment() function in agent_reach/cli.py (lines 975-1014) analyzes system indicators including SSH environment variables, Docker container markers, display availability, and cloud-hypervisor clues to distinguish between local workstations and server infrastructure. If it detects SSH sessions or containerized environments without displays, it returns "server"; otherwise, it defaults to "local".

Can I use local mode on a remote server if I have a browser installed?

While technically possible, forcing local mode with --env local on a headless server will likely cause the installer to fail when attempting to extract cookies from a non-existent or inaccessible browser profile. Server mode is designed specifically for headless environments and should be used for VPS and container deployments regardless of browser installation status.

Why does the installer skip cookie imports in server mode?

The cookie import mechanism relies on accessing local browser databases and potentially triggering OS-level authentication prompts (such as macOS Keychain requests). Since headless servers lack graphical sessions and user-keychain access, the conditional block at agent_reach/cli.py (lines 252-274) explicitly skips configure_from_browser calls when env == "server" to prevent execution errors.

What specific advice does server mode provide that local mode does not?

When running in server mode, the CLI prints warnings about platform-specific IP blocking issues, such as Bilibili blacklisting datacenter IP addresses, and recommends installing residential proxies (visible at lines 81-88). Local mode provides guidance suited for residential networks and desktop browser configurations instead.

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