@beeos-ai/cli 1.0.4 → 1.0.6

package/README.md

@@ -19,7 +19,9 @@ Pure JavaScript — runs on any platform with Node.js 18+. No native compilation
 ### Device agent (Android)
 
 ```bash
-# Attach a USB-connected Android device as an AI agent
+# Attach a USB-connected Android device as an AI agent (launches
+# device-agent + scrcpy-bridge in parallel — the latter powers WebRTC
+# video / control)
 beeos device attach
 
 # Attach a specific device
@@ -28,10 +30,14 @@ beeos device attach --serial SERIAL_NUMBER
 # Attach all connected devices
 beeos device attach --all
 
-# List attached devices
+# Skip the scrcpy-bridge sidecar; run only device-agent (useful for
+# iterating on ACP / Python code without the video stream)
+beeos device attach --no-video
+
+# List attached devices (shows both device-agent and scrcpy-bridge PIDs)
 beeos device list --local
 
-# Detach a device
+# Detach a device (stops device-agent AND scrcpy-bridge)
 beeos device detach --serial SERIAL_NUMBER
 
 # Send a command to a device
@@ -41,6 +47,35 @@ beeos device exec "open Chrome"
 beeos device upgrade
 ```
 
+#### What `attach` does
+
+Under the hood `beeos device attach` orchestrates two sibling processes
+for each device:
+
+1. **device-agent** (Python, ACP over WebSocket) — AI chat, tool
+   execution, file operations. Binds the phone to your BeeOS account
+   and writes identity to `~/.beeos/identity/device-<serial>.key.json`.
+2. **scrcpy-bridge** (Rust, WebRTC) — mirrors screen + audio and
+   forwards touch / key input. Shares the **same** `.key.json` identity
+   file (both `BRIDGE_PRIVATE_KEY_FILE` and `BRIDGE_PUBLIC_KEY_FILE`
+   are set to it) and authenticates to EMQX via Agent Gateway's
+   `/api/v1/device/bootstrap` endpoint — no static MQTT tokens.
+
+Both processes are tracked in `~/.beeos/devices.json`; `detach` and
+`list` operate on the pair atomically. If the scrcpy-bridge binary
+isn't yet installed on your machine, it is downloaded on first attach
+from GitHub Releases into `~/.beeos/bin/` (set
+`$BEEOS_SCRCPY_BRIDGE_BIN` to point at a pre-built binary to skip the
+download, or `$BEEOS_SCRCPY_BRIDGE_RELEASE_URL` for an internal
+mirror).
+
+When running against a local dev control plane (e.g. `api_url =
+http://localhost:9080`), the CLI automatically points scrcpy-bridge at
+`http://localhost:8083` unless `platform.agent_gateway_url` is
+explicitly set to something non-default. Set
+`BEEOS_AGENT_GATEWAY_URL` to override for one-off experiments without
+touching `config.toml`.
+
 ### OpenClaw agent (local AI assistant)
 
 ```bash
@@ -62,6 +97,10 @@ beeos update openclaw
 - **Node.js 18+**
 - **Android devices**: `adb` (Android Debug Bridge) must be in your PATH
 - **device-agent**: Python 3.11+ or [uv](https://astral.sh/uv) (auto-installed on first use)
+- **scrcpy-bridge** (video streaming): auto-downloaded from GitHub
+  Releases on first `device attach`. Supported targets: darwin
+  arm64/x64, linux arm64/x64, windows x64. On unsupported platforms
+  attach still succeeds — only video is skipped.
 
 ## Configuration
 
@@ -70,6 +109,7 @@ Config is stored at `~/.beeos/config.toml`:
 ```toml
 [platform]
 api_url = "https://api.beeos.ai"
+agent_gateway_url = "https://agent-gw.beeos.ai"
 bridge_url = "wss://bridge-sg.beeos.ai"
 dashboard_base_url = "https://beeos.ai"
 
@@ -77,3 +117,34 @@ dashboard_base_url = "https://beeos.ai"
 http_enabled = true
 http_port = 9090
 ```
+
+`agent_gateway_url` is consumed by the scrcpy-bridge sidecar for
+bootstrap (Ed25519-signed `/api/v1/device/bootstrap` calls). Set it
+alongside `api_url` when pointing at a non-default control plane.
+
+## Troubleshooting
+
+### Video stays black / "Reconnecting..." in the viewer
+
+scrcpy-bridge uses `str0m` for WebRTC, which cannot parse Chrome's
+mDNS-hidden ICE candidates (`xxx.local`). In most cases the bridge
+recovers automatically via peer-reflexive candidate learning from the
+browser's outgoing STUN binding, so you should still see video.
+
+If the browser is in a network where outbound UDP to the bridge's
+advertised LAN IPs is blocked, the peer-reflexive fallback won't fire
+and the viewer will keep reconnecting. Two common workarounds while
+debugging locally:
+
+1. Disable Chrome's mDNS hiding for the dev session:
+   open `chrome://flags/#enable-webrtc-hide-local-ips-with-mdns`,
+   set it to **Disabled**, and restart Chrome. Chrome will then
+   advertise real LAN IPs directly.
+2. Make sure a reachable TURN server is configured on the Runtime
+   (`TURN_URLS`, `TURN_USERNAME`, `TURN_CREDENTIAL`). The viewer's
+   `iceServers` are sourced from the `stream-url` API and drive the
+   browser's srflx/relay candidate gathering.
+
+In production, we rely on the TURN relay path; the mDNS issue is
+only a concern when running Chrome + scrcpy-bridge on the same host
+behind restrictive local firewalls.