# ADR-0001: Standalone Bellona Remote Gateway and Remote Host

- **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.

## Related Decisions

- `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/`
