Metadata-Version: 2.4
Name: cua-host-bridge
Version: 0.1.0
Summary: Authenticated MCP streamable-HTTP host bridge: expose a machine's cua-driver desktop to a remote Hermes agent
Author: Ben Kamholtz
License: MIT
Project-URL: Repository, https://github.com/bennybuoy/cua-host-bridge
Keywords: mcp,cua,computer-use,hermes,remote-desktop,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=2.0.0
Requires-Dist: starlette>=1.3.1
Requires-Dist: uvicorn>=0.31.0
Dynamic: license-file

# 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

```bash
# 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

```yaml
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](https://github.com/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).
