Eve library

Bellona Remote Control Compatibility Matrix

Guide

Revision 1

On this page

Matrix date: 2026-04-21

This matrix records the compatibility target for Phase 180 remote-control work. It is not a promise that all rows are implemented today. It separates repo-proven baselines, implementation targets, candidate versions, and blocked surfaces so gateway, host, adapter, MCP, and Control Room work can make explicit support decisions.

Status Legend#

  • Baseline: use for first implementation and automated contract tests.
  • Supported candidate: may be enabled after compatibility tests and hardware/manual evidence.
  • Legacy: existing docs/code mention it, but new privileged work should not start there unless a customer or fixture requires it.
  • Blocked: must remain disabled until later policy, approval, audit, or hardware evidence exists.

Source Hierarchy#

  1. Phase 180 ground rules and ADR-0001 are authoritative for security and architecture boundaries.
  2. Current repo configuration is authoritative for monorepo tooling: package.json, pnpm-workspace.yaml, relevant pyproject.toml files, Bellona domain docs, and audited bridge/runtime code.
  3. Official upstream docs are used for current product lifecycle reality: Node.js releases, Blender LTS/release notes, Unreal Engine 5.6 release notes, Chrome remote debugging behavior, Playwright browser support, Apple capture/permission docs, and WebRTC ICE/STUN/TURN docs.
  4. If repo docs and upstream docs conflict, Phase 180 implementation must use a conservative target and record the wider version as a candidate until tests prove it.

Core Compatibility Matrix#

Surface MVP Baseline Candidate / Test Range Explicitly Blocked or Deferred Verification Required Before Checked Implementation
macOS remote host macOS 14 Sonoma on Apple Silicon for the controlled MacBook. This matches current Unreal requirements better than older desktop-shell docs and keeps host work aligned with modern TCC. macOS 13 Ventura may remain a transitional operator-wrapper minimum because Yemaya Desktop docs already use macOS 13+. macOS 15 is a candidate for future HDR/SM6/advanced capture tests. Intel Macs are not an MVP host target. Unsigned helpers, background input, screen capture, browser profile access, and file grants are blocked until TCC prompts, signing/notarization, policy, approval, and audit are implemented. Hardware/manual evidence on a real Mac for Accessibility, Screen Recording, input injection, foreground app targeting, multi-display capture, sleep/wake reconnect, notarized helper startup, and uninstall/permission reset behavior.
Operator web/desktop Browser-first Bellona Control Room consuming gateway APIs. Desktop wrapper is later distribution/native affordance only. Electron wrapper can reuse Yemaya Desktop's Node 20+/pnpm 10/macOS 13+ build pattern after the web Control Room boundary exists. Renderer-owned privileged execution is blocked. Electron IPC cannot bypass gateway/host protocol, policy, approval, or audit. Playwright desktop/mobile coverage for web UI states; Electron smoke/manual evidence later for native menus, deep links, multi-monitor/PiP, update/signing, and permission diagnostics.
Blender adapter Blender 4.0.x for the first remote adapter because Bellona developer docs require >=4.0 and repo docs list 3.6-4.0. Host talks to the addon on localhost only. Blender 4.2 LTS and 4.5 LTS are supported candidates. Blender 4.5 LTS is current upstream LTS and maintained until July 2027. Blender 3.6 is legacy/read-only unless a fixture requires it. Arbitrary Python, arbitrary file open/save, destructive deletes, render jobs, and import/export are blocked until path grants, policy, approvals, undo/evidence, and audit exist. Vitest/schema adapter tests first, then hardware evidence in Blender for addon install/startup, localhost:9876, main-thread marshaling, safe read-only scene query, safe primitive mutation, timeout/cancel, crash/restart, and evidence capture.
Unreal adapter Unreal Engine 5.3 for the first remote adapter because Bellona developer docs require >=5.3 and repo docs list 5.0-5.3. Unreal 5.4, 5.5, and 5.6 are supported candidates after plugin/API compatibility tests. Upstream UE 5.6 uses macOS 14 and Xcode 16 baselines. Unreal 5.0-5.2 are legacy. Console commands, arbitrary Blueprint calls, destructive actor/level operations, and project file mutation are blocked until protocol schemas, policy, approvals, undo/evidence, and audit exist. Vitest/schema adapter tests first, then hardware evidence in Unreal Editor for version discovery, project open, read-only world query, safe actor spawn in a fixture level, timeout/cancel, editor crash/restart, and screenshot/evidence capture.
Chrome/Chromium/CDP Playwright-managed Chromium for automated tests and isolated automation profiles. Any CDP endpoint remains localhost-only on the host. Branded Google Chrome Stable/Beta through Playwright channels or Chrome for Testing after media-codec and policy checks. Real user profiles are blocked. Chrome remote debugging against the default profile is blocked; Chrome 136+ requires a non-default --user-data-dir for remote debugging switches. Credential/cookie extraction is blocked until the threat model and policy gates allow it. Playwright tests with isolated profiles; adapter tests for tab/page/query commands; manual evidence for real Chrome app control, custom user-data-dir, browser crash/restart, download/upload path grants, redaction, and malicious-page containment.
Node.js runtime Root monorepo baseline is Node.js >=20.0.0 with pnpm pinned to 10.25.0. New Phase 180 TypeScript packages should target Node 22 LTS first while staying compatible with Node 20. Node 24 Active LTS should be added to CI once gateway/host packages exist. Node 20 and 22 are Maintenance LTS lines in the current upstream release table. Node 18 is not a Phase 180 target even though one older Bellona library declares >=18.0.0; the repo root requirement supersedes it for new work. Odd-numbered Current releases are not production baselines. Package build/typecheck/test on the selected CI Node matrix; WebSocket/WebRTC signaling tests; durable storage/client compatibility tests when gateway packages exist.
Python runtime Python 3.11 for Psyche fallback reuse because audited Psyche services use python = "^3.11" and ruff/mypy target py311. Python 3.12 and 3.13 are migration candidates after OpenCV, OCR, aiortc, av, Playwright, and macOS native helper compatibility is proven. Python 3.10 and older are not new remote-host targets. Packaging-tool migration from Poetry to uv is out of scope for this matrix and must be handled as a separate repo-wide tooling task. Existing Psyche lint/test commands for reused code, plus future fallback-library unit tests across screenshot, OCR, accessibility, input, browser, file, and streaming extras. Hardware evidence on macOS is required before any fallback provider is checked.
WebRTC media/data Gateway-authorized signaling first; media streams are disabled by default until policy/audit and hardware evidence exist. Control commands must not depend on media success. Same-LAN direct ICE candidates are candidates after signaling tests. Cloud mode requires TURN for reliable cross-NAT relay. Psyche's optional aiortc/av extras are implementation references. Browser-to-host direct unauthenticated media, unaudited screen sharing, default-open UDP ranges, and media paths that bypass gateway session authorization are blocked. Contract tests for signaling envelopes; network impairment tests for reconnect/backpressure; manual evidence for same-LAN and cross-network ICE/STUN/TURN, degraded state, bitrate/fps adaptation, consent/permission UI, stream redaction, and teardown.
Same-LAN mode Gateway may run on the primary MacBook or another trusted LAN node. Remote Host connects outbound over authenticated WebSocket/WSS. Engine/browser/debug ports stay localhost-only. LAN service discovery is a candidate after pairing/auth exists; until then, explicit gateway URL or pairing code is safer. Host inbound command ports and direct LAN exposure of Blender/Unreal/CDP/desktop control are blocked. Fake gateway/host contract tests, then two-Mac manual evidence for pairing, reconnect, offline/degraded state, command round trip, local stream path, and emergency stop.
Cloud gateway mode Gateway runs in trusted cloud or LAN-cloud edge; Host connects outbound over WSS 443; Control Room/MCP clients use HTTPS/WSS to gateway. Hetzner and AWS are candidate deployment targets. TURN is required for reliable cross-network media; direct peer paths are optimization only. Any design requiring inbound ports on the controlled MacBook is blocked. Production cloud gateway using memory-only session/command/audit state is blocked. Integration tests against fake host and fake client; persistence/audit tests; deployment smoke tests; manual evidence for cross-network host reconnect, TURN relay, command latency, stream degradation, gateway restart, and audit replay.

Version Baselines by Component#

Component / Runtime Repo Evidence Phase 180 Target Notes
Monorepo package manager package.json pins packageManager to pnpm@10.25.0; root engines allow pnpm >=10.0.0. Use pnpm 10.x for Phase 180 commits. Do not introduce npm/yarn lockfiles.
TypeScript Root package.json uses typescript ^6.0.3, root tsconfig.base.json has no ignoreDeprecations override, Nx 22.7.4, Vite catalog ^8.0.14, Vitest ^4.1.7. Known nested package-internal TypeScript 5 compilers are disclosed and constrained by pnpm verify:phase 180. Use existing Nx/Vite/Vitest patterns for new TS packages and keep Phase 180 typecheck targets on TS6. Protocol schemas should include drift checks before implementation packages depend on them; checked-in Bellona Remote targets must not rely on CLI or inherited tsconfig compiler deprecation workarounds.
Python service tooling Psyche services currently use Poetry pyprojects and Poetry-backed Nx targets. Keep existing Poetry verification until a separate uv migration is explicitly scoped and verified. Runtime target is Python 3.11; package-manager modernization must not be mixed into privileged remote-control implementation without a plan.
Bellona engine bridge docs Bellona docs list Blender 3.6-4.0, Unreal 5.0-5.3; developer guide lists Blender >=4.0, Unreal >=5.3. Start adapter implementation at Blender 4.0 and Unreal 5.3, then expand to LTS/current candidates. The matrix intentionally narrows initial targets to avoid overclaiming support from stale docs.
Blender addon runtime Audited addon defaults to localhost:9876, uses Blender bpy, handlers, timers, and main-thread marshaling. Host adapter talks to addon over localhost only and records Blender version/capability metadata. External Python dependencies cannot be assumed inside Blender's embedded interpreter.
Bellona bridge-core Audited bridge-core has lifecycle, heartbeat, request/response, reconnect, and validation precedents. Reuse patterns but not wire contracts; Phase 180 contracts come from libs/bellona/remote-protocol. Existing bridge ports such as 9001 and 9003 remain local adapter concerns, not LAN/cloud surfaces.
Psyche computer-use fallback Pyproject uses Python 3.11 and optional OCR, Playwright, aiortc, av, Docker, database, and cache extras. Extract primitives later into libs/psyche/desktop-fallback; keep fallback subordinate to typed adapters. Existing Linux/Xvfb assumptions must be replaced or wrapped for macOS TCC, ScreenCaptureKit/CG capture, Accessibility, and native input.
Browser automation Repo uses Playwright in TS and Python; studio-web already has Playwright coverage. Use Playwright Chromium for tests, isolated Chrome/Chromium profiles for host browser adapter work. CDP ports remain localhost-only; real profiles and credentials are blocked.
WebRTC Psyche computer-use has optional aiortc/av; README describes H.264/VP9/AV1 streaming; MDN documents ICE use. Gateway signaling contracts first, then same-LAN/TURN media tests. TURN must be part of cloud gateway compatibility, not an optional production afterthought.

Network Mode Compatibility#

Mode Gateway Location Host Connection Client / MCP Connection Stream Path Minimum Evidence Before Support
Same LAN Primary MacBook or trusted LAN machine. Outbound authenticated WS/WSS from controlled MacBook. HTTPS/WSS to LAN gateway. Gateway-signaled WebRTC; direct LAN ICE candidates allowed only after auth and session approval. Two-Mac test: pairing, command round trip, adapter capability report, stream start/stop, network drop/reconnect, audit record, emergency stop.
Cloud gateway Hetzner/AWS/trusted cloud or an edge gateway reachable over WSS 443. Outbound authenticated WSS 443; no inbound host port. HTTPS/WSS to cloud gateway. TURN relay required for reliability; direct peer path is optimization only. Cross-network test: host behind NAT, client on different network, TURN relay, gateway restart, host reconnect, audit replay, command latency/degraded states.
Offline fixture Local fake gateway and fake host in test process or local ports. In-process or localhost-only fake transport. In-process/localhost fake client transport. No real media; fixture stream descriptors and deterministic progress events. Automated contract tests for validation failure, timeout, cancel, idempotency, disconnect, policy deny/allow, approval states, and audit emission.
Direct adapter None. Not permitted for remote-control production. Not permitted. Not permitted. Blocked by Phase 180 localhost adapter rule and ADR-0001; direct exposure of engine, browser, or desktop ports must not be implemented.

Implementation Gates#

  • Protocol schemas and fixtures must encode version/capability metadata for macOS, host runtime, gateway runtime, adapter kind, adapter version, engine version, browser version, Node version, Python version, WebRTC support, and network mode.
  • Gateway and host handshakes must reject unsupported major protocol versions and report degraded candidate support rather than silently enabling it.
  • Adapter capability reports must distinguish read-only, safe mutation, destructive mutation, file-system access, arbitrary script/console, render job, browser profile, desktop fallback, and stream capture permissions.
  • CI can verify schema, gateway, host, and fake-adapter compatibility, but real macOS permissions, Blender, Unreal, Chrome app/profile behavior, WebRTC media, and two-network operation require hardware/manual evidence before the corresponding implementation item is checked.
  • Any matrix expansion must update this file, the implementation tracker, and relevant tests before a new version or mode is advertised as supported.

Upstream Source Anchors#

Official external sources reviewed on 2026-04-21: