cua-host-bridge

Authenticated MCP streamable-HTTP host bridge: expose this machine's desktop to a remote Hermes agent running the remote computer-use provider.

The agent side dials out; the host side (this package) owns cua-driver, its display, and its permissions. A headless gateway with no display and no cua-driver still gets the computer_use tool — the machine that matters is this one.

Quick start

# 1. Install (host machine)
pip install cua-host-bridge        # or: uvx cua-host-bridge

# 2. cua-driver (once)
curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash

# 3. Token (>= 32 bytes)
export HERMES_CUA_REMOTE_TOKEN=$(python3 -c "import secrets; print(secrets.token_hex(32))")

# 4. Run — Host allowlist must include the port: the Host header carries it
cua-host-bridge --port 8765 --allowed-hosts myhost:8765 --allowed-origins http://myhost:8765

On a headless Linux host the bridge auto-starts Xvfb on a free display and openbox.

Security model

• Bearer auth, constant-time compare; token never reaches child process env
• Host/Origin allowlists, no wildcards, exact match — include the port
• Non-loopback plaintext HTTP bind refused without explicit HERMES_CUA_BRIDGE_ALLOW_PLAINTEXT
• DNS-rebinding 421s before auth 401s; Cache-Control: no-store
• Standard permission mode only; no approval bypass
• Long-lived MCP streams: 30s connect/read=None, session idle timeout 1800s

The Hermes side

computer_use:
  provider: remote
  remote:
    enabled: true
    url: https://myhost:8765/mcp

with HERMES_CUA_REMOTE_TOKEN (>= 32 bytes) in the agent's .env.

Origin

Extracted from NousResearch/hermes-agent (MIT, (c) 2025 Nous Research and contributors) — the files are mirrors of the in-tree tools/computer_use/host_bridge*.py; the only drift is the import seam. The client side lives in Hermes as the remote provider (PR #103653).