This guide documents the platform-neutral host runtime contract — the interface
defined in 180.C.26.16 (libs/bellona/host-runtime) — and the exact contract
a Windows host (180.C.36) and a Linux host (180.C.37) implement to
plug in without forking the adapter or command code that the macOS host already
carries.
The whole point of @bellona/host-runtime: adapter and command code must never
branch on process.platform. Each OS ships one HostRuntime (its permission
provider + process launcher + screen-capture descriptor) and registers it; the
rest of the host takes a HostRuntime, not a platform switch. Adding a platform
is a new column in one matrix plus three small implementations, not a rewrite.
Package: @bellona/host-runtime (libs/bellona/host-runtime/src/index.ts),
version 0.1.0.
1. The three contracts a platform implements#
A platform supplies exactly three things, then composes them. All live in
libs/bellona/host-runtime/src/.
1.1 HostRuntime — the aggregate (host-runtime.ts)#
export interface HostRuntime {
readonly platform: HostPlatform; // 'macos' | 'linux' | 'windows'
readonly permissions: HostPermissionProvider;
readonly processes: HostProcessLauncher;
screenCapture(): HostScreenCaptureCapability | Promise<HostScreenCaptureCapability>;
permissionRequirements(): readonly HostPermissionRequirement[];
}
You do not implement this by hand — you call the factory
createHostRuntime(options) (host-runtime.ts), which validates that every
part agrees on the platform (a Windows launcher cannot be smuggled into a Linux
runtime — it throws) and wires permissionRequirements() to the shared matrix:
const runtime = createHostRuntime({
platform: 'linux',
permissions: createLinuxHostPermissionProvider(),
processes: createLinuxHostProcessLauncher(),
screenCapture: () => linuxScreenCaptureCapability(),
});
The macOS reference does exactly this in
apps/bellona/remote-host/src/host-runtime-bridge.ts:createMacHostRuntime, which
adapts the existing macOS TCC detector to the contract and calls
createHostRuntime({ platform: 'macos', … }).
1.2 HostPermissionProvider — detect + guide (permission-provider.ts)#
export interface HostPermissionProvider {
readonly platform: HostPlatform;
detect(): HostPermissionReport | Promise<HostPermissionReport>;
requestGuidance(kind: HostPermissionKind): HostPermissionGuidance;
}
detect()probes the OS for the per-capability grant state and returns aHostPermissionReport. You should not hand-roll the rollup — build the raw per-capability states and call the sharedbuildHostPermissionReport({ platform, checkedAt, states, reasons })(permission-provider.ts), so thenot-applicable/missing/unknownrollup and the required-count logic are identical on every platform.requestGuidance(kind)returns the OS-specific step-by-step instructions for granting one capability (what the operator clicks in System Settings / a portal / a UAC prompt).
A grant state is one of (HostPermissionState):
| State | Meaning |
|---|---|
granted |
The OS has granted the capability. |
denied |
A supported capability the OS refused. |
unknown |
Supported but uncheckable right now (e.g. the probe binary is missing). Distinct from denied. |
not-applicable |
A capability this platform does not support at all. The matrix forces this — a probe can never make an unsupported capability read as denied. |
1.3 HostProcessLauncher — launch/focus (process-launcher.ts)#
export interface HostProcessLauncher {
readonly platform: HostPlatform;
launch(request: HostProcessLaunchRequest): HostProcessLaunchResult | Promise<…>;
focus(request: HostProcessFocusRequest): HostProcessFocusResult | Promise<…>;
}
launch takes an absolute target (executable / .app / .desktop / .exe),
optional args / cwd / env, and an activateExisting flag (reuse a running
instance and bring it forward instead of spawning a new one). The result reports
the concrete OS mechanism used (open, exec, ShellExecute, …), launched,
focused, and processId when the platform exposes it. This thin launcher is the
only per-platform difference in app control — the command layer (which DCC,
which args) is platform-neutral.
1.4 HostScreenCaptureCapability — describe the backend (screen-capture.ts)#
screenCapture() returns a descriptor of the capture backend (e.g.
ScreenCaptureKit on macOS 12+, PipeWire portal / X11 on Linux, DXGI Desktop
Duplication on Windows). The macOS descriptor is
host-runtime-bridge.ts:macHostScreenCaptureCapability.
2. The permission matrix (host-platform.ts) — the single source of truth#
host-platform.ts is where 180.C.36 and 180.C.37 actually "plug in". It defines:
- The platforms:
HOST_PLATFORM_VALUES = ['macos', 'linux', 'windows']. - The capability superset (
HOST_PERMISSION_KIND_VALUES):screen-recording,accessibility,automation,files-and-folders,local-network. - The capability → protocol-scope + label binding (
HOST_PERMISSION_DEFINITIONS) — platform-neutral: only the support/required/authority columns vary. PLATFORM_PERMISSION_MATRIX— the per-platform(supported, required, authority)for each capability. This is the one place you add a platform.
The capability-to-scope binding (stable across all platforms):
Capability (HostPermissionKind) |
Protocol scope (RemotePermissionScope) |
Label |
|---|---|---|
screen-recording |
desktop.observe |
Screen Recording / Capture |
accessibility |
desktop.input |
Accessibility / Synthetic Input |
automation |
process.launch |
Application Automation |
files-and-folders |
file.read |
Files & Folders Access |
local-network |
browser.profile.isolated |
Local Network Access |
2.1 What each platform supports / requires (the live matrix)#
Transcribed directly from PLATFORM_PERMISSION_MATRIX in host-platform.ts.
req = required for core remote-control function; sup = the platform can
detect/grant it at all.
| Capability | macOS | Linux | Windows |
|---|---|---|---|
screen-recording |
sup ✓, req ✓ — macOS TCC | sup ✓, req ✓ — PipeWire / X11 | sup ✓, req ✓ — DXGI Desktop Duplication |
accessibility |
sup ✓, req ✓ — macOS TCC | sup ✓, req ✗ — compositor session | sup ✗ — n/a |
automation |
sup ✓, req ✗ — macOS TCC (Automation) | sup ✗ — n/a (app control is process exec) | sup ✓, req ✗ — Windows UAC |
files-and-folders |
sup ✓, req ✗ — macOS TCC (Files) | sup ✓, req ✗ — POSIX permissions | sup ✓, req ✗ — NTFS ACLs |
local-network |
sup ✓, req ✗ — macOS Local Network | sup ✓, req ✗ — firewall (iptables/nft) | sup ✓, req ✗ — Windows Defender Firewall |
Read the differences carefully — they encode real OS behaviour:
- macOS gates capture and synthetic input behind TCC, and treats app control as a separate Automation grant. Capture + input are both required.
- Linux mediates capture/input through the compositor (a PipeWire portal on
Wayland, X11 otherwise) — there is no separate Accessibility OS grant the way
macOS has, so
accessibilityis supported but not required (it is part of the same compositor session), and there is no OS-level per-app Automation gate, soautomationis not supported (not-applicable, not "denied"). - Windows captures via DXGI with no per-app prompt, and has no
Accessibility-style synthetic-input grant (
not-applicable); elevation (UAC) gates privileged automation.
2.2 Helpers a provider uses#
resolveHostPermissionRequirements(platform)→ the full requirement list for a platform (drives the detection set and operator guidance).resolveHostPermissionRequirement(platform, kind)→ one capability's requirement.hostPermissionScope(kind)→ the stable protocol scope a capability maps onto.
3. How a report becomes gateway-visible permissions#
Written once in permission-provider.ts, reused by every platform — a new
host never re-derives this:
buildHostPermissionReport(...)rolls raw per-capability states into aHostPermissionReportwithmissingRequiredCountand an overallstate(granted | missing | unknown | not-applicable). The rollup rules: required-denied ⇒missing; required-unknown ⇒unknown; an unsupported-only platform ⇒not-applicable; a non-required denial is still surfaced asmissing, but a non-required unknown never drags an otherwise-granted host belowgranted.hostPermissionReportToRemotePermissions(report)projects the report onto the protocol'sRemotePermission[]. Granted capabilities becomerequires-approval, never auto-allowed— the host still gates each command; denied/unknown becomedenied;not-applicablecapabilities are omitted.applyHostPermissionReportToDevice(device, report)merges those permissions into aRemoteDevice, replacing prior host-permission entries (matched by scope) and stamping rollup metadata (hostPermissionState,hostPermissionMissingRequiredCount, …) so the gateway sees a consistent shape across macOS/Linux/Windows.
This is why a Linux host is never falsely reported as "missing a macOS TCC
grant": the unsupported capabilities resolve to not-applicable and are dropped
from the projection entirely.
4. The fail-loud default: NullHostRuntime#
Before a platform is wired, the honest representation of "real but absent" is
createNullHostRuntime(platform) (host-runtime.ts). It does not fabricate:
detect()reports every supported capability asunknown("can't check"), nevergranted.requestGuidance()says the runtime is unconfigured.launch()/focus()/screenCapture()throwHostRuntimeNotConfiguredErrorrather than silently no-op.
This is the correct pattern for an unwired Windows/Linux host today: fail loud, never fake a grant or a launch. It is the opposite of a stub.
5. Step-by-step: implementing a new host (180.C.36 Windows / 180.C.37 Linux)#
The macOS host is the worked reference
(apps/bellona/remote-host/src/host-runtime-bridge.ts). To add a platform:
-
Confirm the matrix column.
PLATFORM_PERMISSION_MATRIX[<platform>]inhost-platform.tsalready has Windows and Linux columns (above). If your OS behaves differently from what is encoded, that table is the single edit — not adapter code. -
Implement
HostPermissionProvider. For eachsupportedcapability, probe the OS and produce a rawHostPermissionState; pass the map tobuildHostPermissionReport({ platform, checkedAt, states, reasons }). Do not reproduce the rollup. ImplementrequestGuidance(kind)with the real OS steps:- Linux: check a working PipeWire portal / X11 capture path for
screen-recording; POSIX perms forfiles-and-folders; firewall reachability forlocal-network.automationisnot-applicable(the matrix forces it). - Windows: DXGI availability for
screen-recording; a UAC/elevation check forautomation; NTFS ACLs forfiles-and-folders; Defender Firewall forlocal-network.accessibilityisnot-applicable.
- Linux: check a working PipeWire portal / X11 capture path for
-
Implement
HostProcessLauncher. Maplaunch/focusonto the OS mechanism — Linux:exec/gtk-launch/ freedesktop activation; Windows:ShellExecute/start/ activate-existing. Report the realmechanismstring and honouractivateExisting(fall back to launching withfocused: falseif you can't). -
Describe
screenCapture()— return the backend descriptor (PipeWire/X11 or DXGI). -
Compose with
createHostRuntime({ platform, permissions, processes, screenCapture })and register it where the macOS bridge is registered. The factory's platform-agreement check is your safety net.
Adapter code, the command executor, and the gateway projection need zero
changes — they already consume HostRuntime and the protocol RemotePermission[]
the shared projection produces.
Honest scope note. The macOS provider/launcher are real (
host-runtime-bridge.ts+ the macOS TCC detector). Windows (180.C.36) and Linux (180.C.37) host implementations of these interfaces are the remaining work; the contract, the matrix columns, the shared rollup/projection, and the fail-loudNullHostRuntimeare all implemented and tested today. Authoring + running a real Windows/Linux capture+input path requires the respective OS and hardware and is not exercised on the Linux CI box.
6. Module map#
| Concern | File | Key symbols |
|---|---|---|
| Platforms + permission matrix | host-platform.ts |
HOST_PLATFORM_VALUES, HOST_PERMISSION_KIND_VALUES, PLATFORM_PERMISSION_MATRIX, resolveHostPermissionRequirements, hostPermissionScope |
| Permission provider + projection | permission-provider.ts |
HostPermissionProvider, HostPermissionReport, buildHostPermissionReport, hostPermissionReportToRemotePermissions, applyHostPermissionReportToDevice |
| Process launch/focus | process-launcher.ts |
HostProcessLauncher, HostProcessLaunchRequest, HostProcessLaunchResult |
| Screen capture descriptor | screen-capture.ts |
HostScreenCaptureCapability |
| Aggregate + factory + fail-loud default | host-runtime.ts |
HostRuntime, createHostRuntime, createNullHostRuntime, HostRuntimeNotConfiguredError |
| macOS reference wiring | apps/bellona/remote-host/src/host-runtime-bridge.ts |
createMacHostRuntime, createMacHostPermissionProvider, createMacHostProcessLauncher, macHostScreenCaptureCapability |
See also: Architecture §3.1–3.2 for where host permissions sit in the trust model, and the cross-platform scope ADR.