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

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 (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.

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.

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

python -m agent_reach.cli install

Force local mode explicitly:

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

Install on a headless server:

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

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

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

Diagnostic Output Variations

The 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 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 (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 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, 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.

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, 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.

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