Eve library

ADR-0004: Cross-Platform Remote Host Scope

ADR

Revision 1

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

Context and Problem Statement#

Phase 180 is titled around a MacBook Remote Host and its target layout names libs/bellona/mac-host-runtime for macOS permissions, process launching, window focus, screen capture, signing, and update helpers. The compatibility matrix also makes macOS 14 on Apple Silicon the remote-host MVP baseline.

The broader product vision is not macOS-only. Blender and Unreal production studios frequently use Windows workstations, Linux render nodes, and mixed-platform farms. The Phase 180 gap analysis therefore added explicit Windows host support (180.C.36), Linux host support (180.C.37), and a cross-platform permission abstraction task (180.C.26.16).

This ADR decides whether Phase 180 remains macOS-only, expands immediately to macOS plus Windows and Linux, or takes a phased approach. The decision controls whether 180.C.36 and 180.C.37 are in scope and whether host runtime code should stay macOS-specific or split into generic interfaces plus platform-specific providers.

Decision Drivers#

  • Deliver the Phase 180 MVP safely against the original two-MacBook use case without diluting early security, pairing, policy, audit, Control Room, and Blender/browser work.
  • Avoid overclaiming support for Windows desktop control, Linux Wayland/X11 capture, service packaging, update channels, UAC/PolicyKit, Defender, AppArmor/SELinux, and cross-platform codec behavior before test rigs exist.
  • Keep protocol, gateway, audit, MCP, adapter, and timeline contracts platform-neutral so future hosts do not require a second control plane.
  • Preserve macOS-specific implementation quality for TCC, Keychain, LaunchAgent, ScreenCaptureKit, Accessibility, code signing, notarization, and operator onboarding.
  • Acknowledge that Windows and Linux hosts are product requirements for production DCC coverage, not speculative nice-to-haves.

Considered Options#

Option 1: macOS Only for All of Phase 180#

Phase 180 would explicitly support only macOS hosts. Windows and Linux would be deferred to a later phase.

Pros:

  • Lowest short-term complexity.
  • Aligns with the original two-MacBook scenario and existing compatibility matrix.
  • Keeps host packaging, permissions, and hardware evidence focused.

Cons:

  • Understates real studio workstation and render-node requirements.
  • Makes the added 180.C.36 and 180.C.37 stages misleading.
  • Encourages macOS assumptions to leak into protocol, gateway, audit, MCP, and adapter contracts.

Option 2: macOS, Windows, and Linux Immediately#

Every host-runtime feature would be designed and implemented for macOS, Windows, and Linux before the MVP is considered complete.

Pros:

  • Strongest platform ambition.
  • Forces generic interfaces early.
  • Avoids later refactoring of host abstractions.

Cons:

  • Too large for the current MVP safety sequence.
  • Requires hardware rigs, packaging pipelines, signing/update plans, and permission models that are not yet inventoried.
  • Delays the foundational gateway, protocol, audit, adapter, and Control Room path before any production feedback exists.
  • Risks implementing lowest-common-denominator desktop fallback instead of deep DCC adapters.

Option 3: Phased Cross-Platform Scope#

Ship the MVP and alpha gates on macOS first. Keep Windows and Linux explicitly in scope for Phase 180 as later expansion stages, but block them behind the macOS MVP, cross-platform host-runtime interface, hardware rig inventory, and platform-specific packaging/security evidence.

Pros:

  • Preserves the original MacBook Remote Host delivery path.
  • Prevents protocol and gateway code from becoming macOS-only.
  • Makes Windows and Linux real Phase 180 work without making them MVP blockers.
  • Lets Windows start with DCC workstation/render-node needs and Linux start with render-node/headless needs before full desktop fallback parity.

Cons:

  • Requires strict discipline to keep early interfaces platform-neutral.
  • Adds future migration work from mac-host-runtime implementation details to generic host-runtime contracts.
  • Requires later hardware evidence across three operating systems.

Decision Outcome#

Bellona adopts Option 3: phased cross-platform scope.

The Phase 180 MVP and alpha gates are macOS-first. The controlled host baseline is the existing compatibility-matrix target: macOS 14 Sonoma on Apple Silicon, with the Remote Host connecting outbound to the Bellona Remote Gateway and all Blender, Unreal, browser, and desktop ports remaining localhost-only.

Windows and Linux hosts remain in scope for Phase 180, but they are later expansion stages rather than MVP blockers:

  • 180.C.36 is in scope for Windows host support after macOS host, policy, audit, Control Room, adapter, packaging, and cross-platform abstraction foundations exist.
  • 180.C.37 is in scope for Linux host support after the same foundations, with render-node/headless operation as the initial Linux emphasis.

The host-runtime split is:

  • apps/bellona/remote-host remains the platform-neutral host application and protocol participant.
  • libs/bellona/mac-host-runtime remains the first concrete provider for macOS-specific permissions, secure credential storage, capture, input, process launching, app discovery, diagnostics, packaging, signing, and update helpers.
  • libs/bellona/host-runtime is introduced later by 180.C.26.16 as the cross-platform interface package for permission state, capture capability, input capability, window/app discovery, process control, credential storage, artifact/diagnostic hooks, codec/stream capabilities, and install/update state.
  • Future libs/bellona/windows-host-runtime and libs/bellona/linux-host-runtime providers may implement the generic interfaces when 180.C.36 and 180.C.37 begin. They must not bypass the gateway, protocol, policy, approval, or audit path.

Normative Rules#

  • MVP host scope: MVP and alpha acceptance remain macOS-first unless a later ADR explicitly revises the release gate.
  • Platform-neutral contracts: libs/bellona/remote-protocol, gateway storage, audit records, timeline events, MCP tools, adapter capability records, and Control Room state must model host OS and runtime capability explicitly rather than assuming macOS.
  • macOS provider quality: mac-host-runtime may use macOS-native APIs and packaging concepts directly. It should not pretend Windows or Linux semantics are available.
  • Generic interface timing: do not introduce a broad host-runtime abstraction until at least one concrete macOS provider path exists and 180.C.26.16 is reached. The abstraction must be extracted from real host needs, not speculative platform guesses.
  • No premature parity claims: Windows and Linux support cannot be checked until platform-specific package install, permissions, capture/input, credential storage, diagnostics, update, security, and hardware evidence are documented and verified.
  • Desktop fallback is platform-specific: desktop screenshot, input, window focus, clipboard, and permission behavior must remain capability-reported per OS. Linux render-node support does not imply Linux desktop control. Windows DCC adapter support does not imply arbitrary Windows desktop automation.
  • Deep adapter first remains global: Blender, Unreal, browser, and other DCC adapters remain preferred over desktop fallback on every OS.
  • No direct engine exposure: Windows and Linux host providers inherit the localhost-adapter rule. Blender, Unreal, Chrome/CDP, desktop, and fallback ports must not be exposed directly to LAN or internet.

Platform Scope by Gate#

Gate / Stage Group macOS Host Windows Host Linux Host
MVP foundation through 180.C.16 In scope and required. Out of MVP gate; protocol must remain platform-neutral. Out of MVP gate; protocol must remain platform-neutral.
Final verification through 180.C.29 Required for the two-MacBook acceptance path. Not required for final Mac MVP unless a later release ADR changes it. Not required for final Mac MVP unless a later release ADR changes it.
Fleet expansion 180.C.30 In scope. Candidate after Windows host stage. Candidate after Linux host stage.
Windows stage 180.C.36 Existing provider remains supported. In scope and required for that stage. Not required for Windows stage.
Linux stage 180.C.37 Existing provider remains supported. Existing provider remains supported once completed. In scope and required for that stage.

Architecture Implications#

  • Remote protocol schemas should include hostOs, hostRuntimeId, hostRuntimeVersion, permissionProvider, captureProvider, inputProvider, and per-capability degraded-state fields before cross-platform providers are advertised.
  • Gateway and Control Room must display capabilities and missing permissions from host reports rather than deriving behavior from OS names alone.
  • Tests for protocol, gateway, host, and mock harness should avoid macOS-only fixture names except where explicitly testing macOS behavior.
  • Windows support should prioritize signed MSI/service install, DCC process discovery, Chrome/Edge isolated profile control, DXGI capture, Defender/UAC policy surfaces, diagnostics, and update rollback.
  • Linux support should prioritize signed packages, systemd user units, headless/render-node roles, Blender/Unreal commandlet operation, PipeWire audio where needed, and explicit Wayland/X11 limitations for desktop fallback.
  • The hardware rig inventory task (180.C.02.15) must list separate macOS, Windows, and Linux fixtures, including virtualized cases that are acceptable only for non-capture/non-input verification.

Acceptance Criteria#

  • This ADR exists under docs/domains/bellona/extras/remote-control/adr/.
  • The decision explicitly selects phased cross-platform host scope.
  • The ADR states that macOS is required for the MVP/alpha host path.
  • The ADR states that 180.C.36 and 180.C.37 remain in scope for later Phase 180 expansion, not MVP blockers.
  • The ADR defines the split between apps/bellona/remote-host, libs/bellona/mac-host-runtime, future libs/bellona/host-runtime, and future Windows/Linux provider packages.
  • The tracker row and Phase 180 checklist item for 180.C.02.14 are updated.
  • Markdown formatting verification passes for this ADR, the tracker, and the phase checklist.

Consequences#

Positive consequences:

  • The Phase 180 MVP remains deliverable against the original controlled-MacBook scenario.
  • Core contracts stay platform-neutral enough for later Windows and Linux hosts.
  • Windows and Linux are explicit product commitments rather than hidden assumptions or indefinite future work.
  • Hardware evidence expectations become clear before platform work starts.

Negative consequences:

  • Early macOS implementation must avoid leaking platform assumptions into shared protocol and gateway records.
  • Cross-platform support arrives later than the first macOS MVP.
  • 180.C.26.16, 180.C.29.16, 180.C.36, and 180.C.37 become necessary follow-through work rather than optional cleanup.
  • docs/domains/bellona/extras/remote-control/adr/ADR-0001-standalone-remote-gateway-and-host.md
  • docs/domains/bellona/extras/remote-control/adr/ADR-0002-remote-control-threat-model.md
  • docs/domains/bellona/extras/remote-control/adr/ADR-0003-gateway-trust-and-e2e-encryption-model.md
  • docs/domains/bellona/extras/remote-control/compatibility-matrix.md
  • Future 180.C.02.15 hardware rig inventory matrix.
  • Future 180.C.02.16 MVP release artifact ADR.
  • Future 180.C.26.16 cross-platform permission abstraction.
  • Future 180.C.36 Windows Host Support.
  • Future 180.C.37 Linux Host Support.

References#