Eve library

ADR-0001: Standalone Bellona Remote Gateway and Remote Host

ADR

Revision 1

On this page
  • Status: Accepted
  • Date: 2026-04-21
  • Authors: Bellona Remote Control Working Group, Codex
  • Reviewers: Bellona, Psyche, Yemaya, Oshun Platform, Oshun Security

Context and Problem Statement#

Phase 180 builds an agent-native creative control plane that lets trusted Oshun agents control Blender, Unreal Engine, Chrome/Chromium, and selected desktop workflows on a second MacBook over same-LAN and cloud-routed networks. The control plane must prefer typed deep integrations over desktop fallback, keep engine debug/control ports bound to localhost, stream live work to operators, and preserve audit-grade traces for commands, approvals, artifacts, and evidence.

Repository audits found useful implementation precedents, but no existing component can safely serve as the privileged remote-control authority:

  • libs/bellona/bridge-core has useful request/response, lifecycle, heartbeat, timeout, and reconnect patterns, but it lacks pairing, authentication, policy, approval, durable audit, idempotency, and protocol ownership.
  • Bellona Blender and Unreal bridge code provides engine adapter precedents and localhost-first control surfaces, but the existing bridges are not remote session authorities and must not be exposed directly to LAN or internet.
  • services/psyche/computer-use provides reusable screenshot, OCR, accessibility, click, key, browser, file, and screen-sharing primitives, but it is a fallback execution surface, not the primary authority for Bellona remote sessions.
  • services/psyche/orchestrator and services/psyche/api-gateway provide session, WebSocket, lifecycle, and event vocabulary, but their current command handling is process-local, partially simulated, and missing the durable security/audit model required for privileged remote control.
  • Yemaya Studio Web/Desktop provide useful UI, native shell, and Playwright patterns, but the Control Room should remain Bellona-owned and gateway-backed rather than coupled to project workspace stores or Electron IPC.

Decision Drivers#

  • Keep the security and audit boundary in Bellona, the domain that owns engine control and creative automation.
  • Support same-LAN and cloud gateway operation without requiring inbound ports on the controlled MacBook.
  • Make protocol schemas the single source of truth before gateway, host, MCP, adapter, and UI implementation starts.
  • Reuse proven local patterns without inheriting unsafe authority, process-local state, or unaudited privileged paths.
  • Preserve deep integration first: Blender, Unreal, and browser APIs should be used before desktop fallback.
  • Provide a clean path for future MCP tools, Control Room UI, audit replay, WebRTC streams, approvals, and policy enforcement.

Considered Options#

Option 1: Reuse Psyche API Gateway and Orchestrator as the Authority#

Psyche already has FastAPI services, session vocabulary, event managers, and WebSocket concepts. That makes it a useful reference for lifecycle naming and subscription shape.

This option is rejected. The audited Psyche services rely on process-local state, permissive token handling, simulated command paths, and missing durable policy, approval, idempotency, replay protection, and audit contracts. Bellona can reuse fallback primitives and selected orchestration vocabulary, but the current Psyche gateway/orchestrator must not become the privileged remote authority.

Option 2: Put Remote Authority in Yemaya Studio Web/Desktop#

Yemaya already has React/Vite, Electron, secure preload patterns, native packaging, project workflow state, and Playwright coverage. That makes it a good implementation reference for future Control Room UI and native operator distribution.

This option is rejected. Remote-control session, command, approval, stream, and audit authority would be wrongly coupled to a production workspace shell. The Yemaya renderer and Electron IPC layer should consume Bellona protocol-backed state when embedding or wrapping Control Room surfaces, not decide privileged remote command execution.

Option 3: Extend Existing Bellona Bridge Apps Directly Across the Network#

Bellona bridge-core and engine bridge apps already provide WebSocket request/response patterns and localhost engine integration precedents. Reusing that directly would minimize initial scaffolding.

This option is rejected as an authority model. The bridge apps do not provide pairing, device identity, policy, approvals, durable audit, session replay, capability negotiation, or protocol ownership. Engine bridge ports must remain localhost-only. Existing bridge code can be reused behind host-side adapter boundaries after the gateway and host enforce protocol, policy, and audit.

Option 4: Build a Standalone Bellona Remote Gateway and Remote Host#

Build a Bellona-owned gateway as the remote-control authority and a Bellona-owned host runtime that runs on the controlled MacBook and connects outbound to the gateway. Reuse Bellona bridge adapters locally behind host adapter boundaries and extract Psyche desktop fallback primitives as a fallback library.

This option is chosen. It creates the right trust boundary, supports LAN and cloud operation, avoids direct exposure of engine/debug ports, gives MCP and Control Room clients a single protocol authority, and lets future work add durable storage, pairing, policy, approvals, audit, stream signaling, and adapter execution incrementally.

Decision Outcome#

Oshun will implement a standalone Bellona Remote Gateway plus a standalone Bellona Remote Host.

The Remote Gateway is the authoritative service for device identity, pairing, session lifecycle, command intake, command routing, idempotency, approval state, policy integration, audit emission, event subscriptions, MCP access, and WebRTC/WebSocket signaling. It may run on the local network or in a cloud environment. Production gateway state must be durable; memory-only state is acceptable only for tests and clearly marked development harnesses.

The Remote Host runs on the controlled MacBook. It establishes an authenticated outbound connection to the Remote Gateway, reports device capabilities and health, manages local adapter registration, executes gateway-authorized command lifecycles, captures local evidence, and reports progress/results back through the gateway. The host must not require inbound LAN or internet ports for normal operation.

libs/bellona/remote-protocol is the canonical schema source for device, session, command, result, approval, audit, stream, adapter, and versioning contracts. Gateway, host, MCP, adapters, tests, and docs must import or generate from those schemas rather than defining parallel contracts.

libs/bellona/remote-adapters will hold typed adapter interfaces for Blender, Unreal, browser, desktop, file, and process targets. Existing Bellona bridge and engine libraries may be used behind those adapter interfaces, but only through localhost-bound host adapters that preserve policy and audit semantics.

Psyche computer-use primitives will be reused as a Bellona desktop fallback library, expected later as libs/psyche/desktop-fallback. Screenshot, OCR, accessibility, input, browser, file, and screen-sharing helpers can be wrapped there, but fallback execution remains policy-gated, approval-aware, audited, and subordinate to typed deep adapters.

Normative Rules#

  • Gateway authority: remote devices, sessions, commands, approvals, audit records, subscriptions, and MCP tool access are authorized through the Bellona Remote Gateway.
  • Host outbound-only default: the controlled MacBook connects outbound to the gateway. Blender, Unreal, Chrome/CDP, and desktop-control ports are not exposed directly to LAN or internet.
  • Protocol source of truth: libs/bellona/remote-protocol owns the command and event schemas consumed by gateway, host, adapters, MCP, tests, docs, and future Control Room UI.
  • Adapter isolation: deep adapters are preferred first. Existing Bellona bridge-core, Blender, and Unreal libraries are reusable only behind host-local adapter boundaries and protocol-level policy/audit checks.
  • Psyche fallback boundary: Psyche computer-use code is a source of fallback primitives, not a remote-control authority. Desktop fallback is allowed only after policy, approval, and audit conditions are satisfied.
  • No hidden privileged paths: arbitrary shell, arbitrary Python, Unreal console commands, desktop control, file-system access, and real browser profile access require explicit protocol schemas, policy decisions, approvals where needed, and audit evidence.
  • Observable execution: every command must carry actor, device, session, command, correlation, target adapter, policy, approval, result, and evidence metadata as soon as those schemas exist.
  • Control Room as client: the Bellona Control Room and any Yemaya/Electron wrapper consume gateway state and submit gateway commands. They are not command authorities.

Architecture Implications#

  • Later scaffolding should create protocol contracts before gateway, host, MCP, adapter, and UI packages rely on concrete command shapes.
  • The gateway walking skeleton should accept outbound host connections, validate handshakes, track device/session state, dispatch commands to fake hosts, and emit audit records before real engine adapters are enabled.
  • The host walking skeleton should load development identity, connect outbound, publish capabilities, route commands through a fake adapter registry, and deny unknown commands until real policy is available.
  • WebRTC media/data paths may later optimize direct LAN streaming, but signaling and authorization still flow through the gateway.
  • Bellona bridge-core lifecycle, heartbeat, timeout, and reconnect patterns are implementation references, not the remote protocol contract.
  • Psyche fallback extraction should avoid importing current process-local orchestrator/gateway authority into Bellona.
  • Yemaya and desktop-shell integration should wait until the Bellona gateway, host, protocol, and Control Room client boundaries are established.

Acceptance Criteria#

  • This ADR exists under docs/domains/bellona/extras/remote-control/adr/.
  • The selected architecture is standalone Bellona Remote Gateway plus standalone Bellona Remote Host.
  • The ADR records why Psyche fallback primitives and Bellona bridge adapters are reused behind boundaries rather than promoted to remote-control authority.
  • The tracker row and Phase 180 checklist item for 180.C.02.08 are updated.
  • Markdown formatting verification passes for this ADR, the tracker, and the phase checklist.

Consequences#

Positive consequences:

  • Bellona gets a clear privileged trust boundary and a single gateway authority for MCP, Control Room, host, adapter, policy, and audit flows.
  • Controlled Macs can participate across LAN or cloud networks without exposing engine/debug ports directly.
  • Existing Bellona bridge and Psyche fallback work can be reused without inheriting unsafe authority models.
  • Later threat modeling, protocol versioning, compatibility testing, and audit replay have a stable architectural anchor.

Negative consequences:

  • The phase must scaffold more contracts and services before user-facing remote control is visible.
  • Some gateway/session ideas overlap with Psyche concepts until reusable primitives are extracted cleanly.
  • The host/gateway split requires additional contract tests and local harnesses before real Blender, Unreal, browser, and desktop adapters are enabled.
  • docs/adr/ADR-0005-api-contract-approach.md
  • docs/adr/ADR-0046-oshun-studio-api-gateway-and-bff-composition.md
  • Future 180.C.02.09 compatibility matrix.
  • Future 180.C.02.10 external implementation research note.
  • Future 180.C.02.11 threat-model ADR.

References#

  • TODOS/phase-180.md
  • docs/domains/bellona/extras/remote-control/implementation-tracker.md
  • libs/bellona/bridge-core/
  • apps/bellona/bridge-blender/
  • apps/bellona/bridge-unreal/
  • libs/bellona/blender/
  • libs/bellona/unreal/
  • services/psyche/computer-use/
  • services/psyche/orchestrator/
  • services/psyche/api-gateway/
  • apps/yemaya/studio-web/
  • apps/yemaya/studio-desktop/