Server Environment Limitations for OpenCLI-Based Channels in Agent Reach

OpenCLI-based channels are automatically disabled on server environments because they require a graphical Chrome instance and cannot function in headless mode, VPS containers, or remote SSH sessions.

Agent Reach treats OpenCLI-based channels—including facebook, instagram, reddit, xiaohongshu, and the core opencli backend—as desktop-only integrations. When the CLI installer runs on a headless server or container, it detects the non-desktop environment and skips these channels entirely to prevent failed installations.

Why OpenCLI Requires a Desktop Environment

OpenCLI-based channels depend on a real Chrome browser session controlled via a Chrome extension. Unlike API-based integrations, these channels cannot operate without the Chrome UI because the extension requires an actual graphical window to interact with web pages.

In agent_reach/cli.py, the installer defines a constant OPENCLI_ONLY_CHANNELS that lists all channels requiring this desktop-only backend. When the environment detection logic identifies a server-class host, it removes any channel in this list from the installation queue before attempting setup.

• Source: agent_reach/cli.py lines 30-37 define the environment detection and skip logic for OpenCLI channels.

How Environment Detection Works

The _detect_environment() function in agent_reach/cli.py (lines 77-99) determines whether the current process runs on a local desktop or a remote server by scoring multiple system indicators:

• SSH environment variables (e.g., SSH_CONNECTION, SSH_CLIENT)
• Docker markers (.dockerenv, docker in cgroup)
• Missing DISPLAY environment variable (indicating no GUI)
• Cloud VM identifiers (AWS, GCP, Azure metadata endpoints)
• Virtualization detection via systemd-detect-virt

If the detection score is greater than or equal to 2, the function returns "server"; otherwise it returns "local". This binary classification drives the entire installation allowance logic for OpenCLI channels.

Automatic Skip Logic on Servers

When _detect_environment() returns "server", the installer executes a hard filter before dependency resolution:

1. The installer checks if any requested channels belong to OPENCLI_ONLY_CHANNELS.
2. If detected, it prints a localized notice explaining that OpenCLI requires a desktop environment and Chrome.
3. It removes these channels from the active installation list.
4. The _install_opencli_deps function is never called, preventing Node.js and browser automation setup attempts.

This safeguard appears in agent_reach/cli.py lines 63-66, where the CLI outputs a message indicating which channels were skipped due to server environment constraints.

Channel Health Check Integration

Even if a user manually forces installation, individual channels validate OpenCLI availability through the base class in agent_reach/channels/_opencli_site.py (lines 13-36).

Each OpenCLI-based channel delegates its health check to opencli_status. If the backend reports "not ready"—which occurs when Chrome is unavailable or the environment is headless—the channel marks itself as unavailable. This prevents runtime failures by ensuring the CLI recognizes these channels as inactive when running on servers.

Bypassing Server Limitations (Not Recommended)

While the automatic detection protects against failed installs, Agent Reach allows forced override via the --env flag. However, this only works if the server actually possesses a GUI and Chrome installation.

Default Behavior on a Server

When running on a VPS or container without graphics support, OpenCLI channels are automatically excluded:

# Running on a headless server (SSH, Docker, no DISPLAY)

$ agent-reach install --env auto --channels all
Environment: Server/VPS (auto-detected)

  -- OpenCLI 需要桌面环境 + Chrome，服务器环境跳过：facebook, instagram, opencli, reddit, xiaohongshu
...

Forcing Local Environment Mode

To attempt installation despite server detection, explicitly specify --env local:

$ agent-reach install --env local --channels opencli,facebook
Environment: Local computer (forced)

Setting up OpenCLI (browser-session backend, desktop only)...

Warning: This command succeeds only if the host actually has a display server and Chrome installed. Without these, the OpenCLI health check will fail and the channels will remain unavailable.

Querying Environment Detection Programmatically

You can inspect how the CLI classifies your current machine using Python:

from agent_reach.cli import _detect_environment

# Returns "local" on laptops/workstations, "server" on headless VMs

print(_detect_environment())

Summary

• OpenCLI-based channels (facebook, instagram, reddit, xiaohongshu, opencli) require a graphical Chrome instance and cannot run on headless servers.
• The _detect_environment() function in agent_reach/cli.py auto-detects server environments by checking for SSH, Docker, missing displays, and virtualization markers.
• When a server is detected, the installer automatically skips OpenCLI channels to prevent failed installations.
• Health checks in _opencli_site.py ensure these channels report as unavailable when Chrome automation is impossible.
• Users can force --env local to bypass detection, but this requires an actual GUI and Chrome installation on the server to function.

Frequently Asked Questions

Can I run OpenCLI channels on a VPS with a desktop environment installed?

Yes, but you must explicitly force the local environment using --env local during installation. The auto-detector will still classify it as a server unless you override it. However, the VPS must have an active X11 or Wayland display, a running Chrome instance, and the Chrome extension installed; otherwise the OpenCLI health check will fail and the channels will remain inactive.

What exact criteria classify an environment as "server" in Agent Reach?

According to agent_reach/cli.py, the _detect_environment() function assigns points for server indicators including SSH environment variables (SSH_CLIENT, SSH_CONNECTION), Docker/container presence, missing DISPLAY variables, cloud provider metadata (AWS, GCP, Azure), and output from systemd-detect-virt. If the cumulative score reaches 2 or higher, the environment is classified as "server", triggering the OpenCLI channel exclusion.

Why can't OpenCLI run in headless mode like Selenium or Puppeteer?

OpenCLI relies on a Chrome extension for browser automation, which requires an actual graphical Chrome window to interact with web pages. Unlike pure automation libraries that can use --headless mode, the extension architecture needs the Chrome UI to be present. This dependency is hardcoded into the channel design in agent_reach/channels/_opencli_site.py, making headless operation impossible regardless of configuration flags.

Is there a way to install OpenCLI dependencies on a server without the GUI?

No. The _install_opencli_deps function in agent_reach/cli.py (lines 51-58) explicitly describes OpenCLI as "desktop only" and requires Node.js and a Chrome binary. The installer will abort if Chrome is missing, and the automated skip logic prevents this function from running entirely on server environments. Without a display server and Chrome, the underlying browser automation cannot initialize.

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