Bellona remote host walking skeleton for Phase 180.
This host process provides local process health/readiness, strict configuration
loading, structured logging, graceful shutdown, a macOS Keychain-backed identity
store, a pairing client, an outbound gateway connection manager, a fake local
adapter registry, a host command executor, and Nx build, typecheck, lint, and
test targets. macOS LaunchAgent packaging is implemented by later 180.C.06
tasks.
The local health server binds to 127.0.0.1 by default. It is intended for
developer diagnostics and future host supervisor checks, not as a public control
surface.
Host runtime logs use the shared Bellona remote structured logging fields from
@bellona/remote-protocol. Gateway-connection, command-execution, HTTP,
identity, and shutdown logs include serviceRole, eventType, and the
available correlation fields: correlationId, sessionId, commandId,
deviceId, connectionId, actorParticipantId, idempotencyKey, and command
target fields. Host logs avoid emitting signed host tokens or personal identity
file paths. Health/readiness payloads report only identity load status, device
id, and storage kind.
Endpoints#
GET /healthGET /v1/healthGET /readyGET /v1/ready
Configuration#
BELLONA_REMOTE_HOST_HEALTH_HOSTorHOST, default127.0.0.1BELLONA_REMOTE_HOST_HEALTH_PORTorPORT, default4071BELLONA_REMOTE_HOST_GATEWAY_URL, defaultws://127.0.0.1:4070/v1/hosts/connectBELLONA_REMOTE_HOST_GATEWAY_RECONNECT_INTERVAL_MS, default1000BELLONA_REMOTE_HOST_GATEWAY_RECONNECT_MAX_ATTEMPTS, default10BELLONA_REMOTE_HOST_GATEWAY_RECONNECT_MAX_INTERVAL_MS, default10000BELLONA_REMOTE_HOST_IDENTITY_STORAGE, defaultmacos-keychain; set todevelopment-fileonly for explicit local test fixturesBELLONA_REMOTE_HOST_KEYCHAIN_ACCOUNT, defaultdefaultBELLONA_REMOTE_HOST_KEYCHAIN_SERVICE, defaultcom.oshun.bellona.remote-host.identityBELLONA_REMOTE_HOST_IDENTITY_FILE, default~/.oshun/bellona/remote-host.identity.dev.jsonwhenBELLONA_REMOTE_HOST_IDENTITY_STORAGE=development-fileBELLONA_REMOTE_HOST_LOG_LEVEL, defaultinfoBELLONA_REMOTE_HOST_PAIRING_EXCHANGE_URL, default derived fromBELLONA_REMOTE_HOST_GATEWAY_URLas/v1/pairing/exchangeBELLONA_REMOTE_HOST_SHUTDOWN_GRACE_MS, default5000NODE_ENV, defaultdevelopment
BELLONA_REMOTE_HOST_GATEWAY_URL must use ws: or wss:. The URL is validated
now so the later outbound connection task can fail fast on invalid host
configuration.
BELLONA_REMOTE_HOST_PAIRING_EXCHANGE_URL must use http: or https:. When it
is not provided, the host derives it from the configured gateway WebSocket URL.
Identity Storage#
180.C.16.01 replaces the default development credential file with macOS
Keychain storage for the Remote Host device identity, deviceKeyId, token
expiry, and signed hostToken. The default store writes a single generic
password item under service com.oshun.bellona.remote-host.identity and account
default. The implementation invokes /usr/bin/security with -w as the final
argument and sends the serialized identity over stdin, so the signed token is
not placed in the process argument list.
Stored Keychain identities use this shape:
{
"schemaVersion": 1,
"storage": "macos-keychain",
"device": {
"id": "device:studio-macbook-air",
"displayName": "Studio MacBook Air"
},
"credentials": {
"authScheme": "bellona-host-token-v1",
"deviceKeyId": "device-key:studio-macbook-air-development",
"expiresAt": "2026-07-21T00:00:00.000Z",
"hostToken": "bellona-host-token-v1.<payload>.<signature>"
},
"createdAt": "2026-04-22T00:00:00.000Z",
"updatedAt": "2026-04-22T00:00:00.000Z",
"metadata": {
"owner": "local-development"
}
}
The device object above is abridged for readability. In tests and real host
Keychain records it must be a complete RemoteDevice from
@bellona/remote-protocol. The legacy development-file store remains
available only by setting
BELLONA_REMOTE_HOST_IDENTITY_STORAGE=development-file for deterministic local
fixtures; that schema still includes keychainReplacementTask: "180.C.16.01" so
old fixture files fail loudly if they drift.
Pairing#
The host exposes an internal pairing client through app.pairingClient. It
posts a one-time pairing code plus a complete RemoteDevice report to the
gateway pairing exchange endpoint, parses the returned signed host token
credentials, and writes the selected identity store. By default, paired
credentials are saved to macOS Keychain; explicit development-file fixtures
still write atomically to the configured file path. mTLS remains later transport
hardening.
Important behavior:
- gateway rejection does not write or partially update local credentials
- the selected identity store persists the complete paired
RemoteDevice,authScheme,deviceKeyId,expiresAt, and signedhostToken - the saved metadata records the pairing exchange URL for local diagnostics
- Keychain-backed identities overwrite stale credentials for the same service/account using the system Keychain update operation
Gateway Connection#
After loading identity, the host opens an outbound WebSocket connection to
BELLONA_REMOTE_HOST_GATEWAY_URL, sends a protocol-valid host.handshake with
the signed host token from the identity store, and auto-responds to gateway ping
heartbeats through the ws client. Unexpected disconnects schedule reconnect
attempts with bounded backoff. Explicit host shutdown closes the socket and does
not reconnect.
Adapter Registry#
The host registers an in-process fake Blender adapter for the walking skeleton:
- adapter id:
adapter:blender-local - capability id:
capability:blender-scene-query - routed command:
blender.scene.query
The registry validates every adapter and capability with
@bellona/remote-protocol, reports adapter health in host health payloads, and
can route a protocol-valid RemoteCommandEnvelope to the fake handler. The fake
handler returns deterministic scene-query output and is intentionally limited to
test/development use.
The host also registers a dynamic state adapter matching the 180.C.03.15
protocol contract:
- adapter id:
adapter:remote-host-state - capability ids:
capability:agent-readiness,capability:state-snapshot - routed commands:
agent.readiness,state.snapshot
state.snapshot returns the current modal-dialog list, shader compile counts,
project-root writability, active/queued command jobs, and disk/memory pressure.
agent.readiness evaluates those same fields with adapter health and macOS TCC
state so agents can see blocking and degraded conditions before attempting a
command that would otherwise fail.
The host registers an in-process browser discovery adapter:
- adapter id:
adapter:browser-local - capability id:
capability:browser-managed-profile-discovery - routed command:
browser.adapter.discovery
The browser discovery command reports Chrome/Chromium executable availability,
the Bellona-managed profile root, localhost-only CDP launch readiness, and
Playwright package/browser availability. Real profile access remains blocked;
managed browser commands only use Bellona-created isolated profile directories.
The detailed operator policy and future unlock criteria live in
docs/domains/bellona/extras/remote-control/browser-profile-isolation.md.
The host registers in-process Unreal discovery, mocked project-info, and mocked world-query capabilities, plus the first safe actor-spawn mutation:
- adapter id:
adapter:unreal-local - capability ids:
capability:unreal-adapter-discovery,capability:unreal-project-info,capability:unreal-world-query,capability:unreal-actor-spawn - routed commands:
unreal.adapter.discovery,unreal.project.info,unreal.world.query,unreal.actor.spawn
The Unreal discovery command reports discovered Unreal Engine installations,
selected engine version and executable path, configured .uproject metadata,
Bellona Unreal plugin descriptor/enabled state, editor process state, the
localhost-only Remote Control endpoint placeholder, authenticated Bellona plugin
readiness on 127.0.0.1:30180, and the currently supported command list.
Discovery remains routable when Unreal, a project, or the plugin is missing so
agents receive structured blockers and remediation context instead of probing
direct editor APIs. Set BELLONA_UNREAL_PLUGIN_SESSION_TOKEN in the Remote Host
and the matching Unreal Editor plugin launch environment or pass
pluginConnection.sessionToken in tests to enable the ready probe. The host
rejects non-loopback Bellona plugin endpoints and treats missing/failed
authentication as degraded readiness, not live editor authority.
unreal.project.info validates the protocol-owned read-only argument and
response schema, then returns a mocked project report from local discovery data:
project path/name, engine version, plugins, modules, target platforms, content
roots, build target metadata, source-control state, config summary, and Bellona
plugin/Remote Control support. unreal.world.query validates a bounded
read-only schema and returns mocked world/map, persistent level, actor class
counts, actor sample, selection, shader compile, editor busy, and structured
blocker data. Neither command writes .uproject, config, generated project,
plugin, map, level, or actor state. 180.C.15.06 routes both read-only commands
through the gateway-host-adapter path with gateway audit entries and timeline
events before any safe mutation is enabled.
180.C.15.07 enables unreal.actor.spawn as a schema-validated safe mutation.
The host parses the protocol-owned command envelope, advertises
command.execute.safe-mutation plus project.write, blocks observe-only
sessions in host preflight, and returns a protocol-valid spawn result with a
spawned actor summary, explicit object reference, committed undo_stack
transaction/undo checkpoint metadata, and a screenshot/evidence placeholder. The
default implementation remains mocked and does not write project files; live
plugin-backed spawn and screenshot capture remain hardware-smoke work.
180.C.15.06 also adds a remote-path smoke command:
pnpm nx unreal:readonly-remote-smoke @bellona/remote-host
The smoke starts an ephemeral gateway, starts an outbound host with the Unreal
adapter registration, dispatches unreal.project.info and unreal.world.query
through the gateway command dispatcher, validates the protocol output schemas,
and prints timeline/audit evidence for both commands.
180.C.15.09 adds an optional fixture-project smoke command for read-only query
and actor spawn:
pnpm nx unreal:actor-spawn-remote-smoke @bellona/remote-host
The command exits with a structured skipped summary unless
BELLONA_UNREAL_HARDWARE_SMOKE=1 is set. When enabled, set
BELLONA_UNREAL_PROJECT_PATH to a fixture .uproject; optionally set
BELLONA_UNREAL_PLUGIN_DESCRIPTOR_PATH, BELLONA_UNREAL_PLUGIN_SESSION_TOKEN,
BELLONA_UNREAL_PLUGIN_HOST, BELLONA_UNREAL_PLUGIN_PORT, and
BELLONA_UNREAL_REMOTE_CONTROL_PORT. Use -- --required or
BELLONA_UNREAL_HARDWARE_SMOKE_REQUIRED=1 to fail if Unreal Engine, the fixture
project, the Bellona plugin, or a running editor process is missing. The smoke
validates unreal.project.info, unreal.world.query, and unreal.actor.spawn
outputs and prints hardware evidence fields including project path, plugin
descriptor, editor process id, command ids, actor id, transaction id, undo
checkpoint id, and screenshot placeholder status.
180.C.15.10 closes the Unreal read-only and safe mutation MVP in
unreal-readonly-safe-mutation-mvp-closure.md.
The closure records the deterministic protocol, host, gateway, policy, audit,
timeline, transaction, and evidence-placeholder coverage, and separates it from
live Unreal fixture evidence that must be collected with the optional hardware
smoke above.
180.C.11.02 adds isolated managed profile directory primitives. Profiles are
created only under the Bellona-managed root, use a bellona-profile- directory
prefix, write a bellona-profile.json marker, and clean up with recursive
removal of the managed directory. The host rejects configured roots and cleanup
paths that point at Chrome/Chromium real profile locations such as Default,
Profile N, Google Chrome user-data roots, or Chromium user-data roots.
180.C.11.04 through 180.C.11.06 add the managed browser session capability:
- capability id:
capability:browser-managed-session - routed commands:
browser.launch_managed,browser.navigate,browser.snapshot,browser.screenshot,browser.close
browser.launch_managed creates an isolated managed profile, launches
Chrome/Chromium through Playwright, binds the Chromium remote-debugging endpoint
to 127.0.0.1, validates the returned CDP WebSocket URL is loopback-only, and
returns a protocol-valid RemoteBrowserManagedSession. Launch failures close
any created browser context and recursively remove the managed profile.
browser.close closes the stored context and removes the managed profile. URL
navigation and snapshots are read-only commands that enforce blocked-domain
policy before Playwright touches the page. The default policy blocks
credentialed URLs, loopback/private/link-local IP ranges, localhost,
.localhost, and .local names; BELLONA_BROWSER_BLOCKED_DOMAINS or adapter
options can add exact or *.example.test domain rules. browser.screenshot
captures through Playwright, applies selector-mask redaction hooks for
redactSelectors, writes the image under BELLONA_BROWSER_ARTIFACT_ROOT or the
host default browser artifact directory, and returns protocol RemoteArtifact
and RemoteAuditEvidence references for gateway registration.
Browser mutating commands also carry compensating-action metadata. The protocol
catalog documents that browser.launch_managed is reversed by browser.close
with managed-profile cleanup, while browser.close is manual_remediation_only
because the isolated profile is intentionally removed. See
docs/domains/bellona/extras/remote-control/browser-compensating-actions.md for
the current catalog and future browser mutation requirements.
180.C.11.10 adds a remote browser CLI smoke:
pnpm nx browser:managed-remote-smoke @bellona/remote-host
The smoke starts an ephemeral Remote Gateway and Remote Host, launches an
isolated managed browser session through the gateway-host path, navigates to
https://example.com/, captures a snapshot, captures a screenshot artifact,
closes the browser session, verifies managed profile cleanup, and prints audit
and timeline evidence. Add -- --url https://example.com/ to use another
allowed public HTTPS page, -- --keep-artifacts to retain the temporary
screenshot artifact directory, or -- --mock-browser to use deterministic fake
browser handles while still exercising the gateway-host-adapter command path.
The host also registers an in-process diagnostics adapter:
- adapter id:
adapter:host-diagnostics - capability id:
capability:host-diagnostics-snapshot - routed command:
diagnostic.host.snapshot
The diagnostics command returns host OS/version details, the current adapter and capability inventory, macOS permission diagnostics, and resource placeholders.
macOS Permission Diagnostics#
On macOS hosts, the runtime probes the platform TCC state for Screen Recording
and Accessibility before advertising desktop fallback readiness. The detector
uses local Swift probes for CGPreflightScreenCaptureAccess() and
AXIsProcessTrusted(), maps Screen Recording to desktop.observe, maps
Accessibility to desktop.input, and reports each check as granted,
missing, or unknown.
Granted macOS TCC state does not grant command execution by itself. The
generated host permissions still use requires-approval so gateway policy and
operator approval remain in the command path. Missing or unknown macOS
permissions are advertised as denied host permissions with remediation text for
System Settings > Privacy & Security. The diagnostics adapter also includes the
same checks in diagnostic.host.snapshot, allowing operators and future support
bundles to see exactly which local permission blocks desktop fallback.
Non-macOS hosts report the checks as not-applicable and do not mutate the
device permission list.
Desktop Screenshot Fallback#
180.C.13.02 adds the first desktop fallback command:
- adapter id:
adapter:desktop-fallback - capability id:
capability:desktop-screenshot - routed command:
desktop.screenshot
The command is macOS-only and requires Screen Recording to be granted by the
local TCC permission detector. It captures a selected display through
screencapture -D <display> or a known window through
screencapture -l <windowid>, writes a retained PNG under
BELLONA_DESKTOP_ARTIFACT_ROOT or the host default DesktopArtifacts directory,
and returns protocol-valid RemoteArtifact and RemoteAuditEvidence records.
Redaction is fail-closed. Callers can provide blackout rectangles in screenshot pixel coordinates; the host applies those blackout regions before writing the retained artifact and records redaction hook placeholders, labels, and a regions hash in artifact metadata. If a redaction hook is requested and cannot return redacted output, the command fails instead of retaining an unredacted artifact.
Gateway artifact registration uses the existing command-result path: host
results include artifact, artifacts, artifactIds, evidence, and
evidenceIds, and the gateway registers screenshot artifacts from those
returned records.
Desktop Window Fallback#
180.C.13.03 extends adapter:desktop-fallback with two macOS-only commands:
desktop.window.listthroughcapability:desktop-window-listdesktop.window.focusthroughcapability:desktop-window-focus
Window schemas live in @bellona/remote-protocol. The host implementation uses
a Swift CoreGraphics/AppKit/Accessibility helper so window inventory is
structured rather than parsed from AppleScript text. List results include window
id, app name, owner pid, title, bounds, display id/index, z-order, layer,
on-screen state, alpha, and best-effort focused state.
desktop.window.list requires Screen Recording because macOS may redact or hide
window metadata without that TCC grant. desktop.window.focus requires both
Screen Recording and Accessibility because the host first resolves the selected
window and then activates the owning app and raises the matching AX window.
Selectors can use a known windowId, appName, title, or a combination of
those fields. The focus result reports whether focus was verified, the matched
window, the verified post-focus window, and a human-readable reason.
Desktop Coordinate Normalization#
180.C.13.04 adds protocol-owned coordinate schemas and a host-side pure
normalizer exported as normalizeRemoteHostDesktopCoordinate(). The normalizer
uses one canonical intermediate space, absolute macOS display points, and maps
between:
- display points
- display pixels with Retina scale factors
- window-relative points
- window-relative pixels
- screenshot pixels
- stream-normalized coordinates
The coordinate context carries display bounds/scale, optional selected-window
bounds, optional screenshot bounds and pixel size, and optional stream capture
region metadata. Callers can request clamping to the target coordinate space
before later desktop input commands use the normalized point. The helper is
intentionally pure and testable so desktop.click can audit both the original
coordinate and the normalized coordinate without invoking macOS input APIs.
Desktop Click Fallback#
180.C.13.05 adds desktop.click through capability:desktop-click. The
command is macOS-only and fails closed unless all of these checks pass before
input dispatch:
- Screen Recording is granted so the host can resolve the selected window.
- Accessibility is granted so the host can post input through Core Graphics.
- The command carries an explicit
desktop.inputcontrol-permission grant. - The selected app/window is currently focused.
- The focused window matches the command allowlist by app name, title fragment, or window id.
- The requested coordinate normalizes inside that focused window.
The host resolves the current window with the existing desktop.window.list
backend, then normalizes the requested point with
normalizeRemoteHostDesktopCoordinate() before invoking the click backend. The
default backend posts a moved/down/up sequence with a Swift Core Graphics helper
using CGEvent and cghidEventTap. Results include the original allowlist, the
target focused window, the display point, the display-pixel point, and the
normalized coordinate record for audit.
180.C.13.06 adds visual verification around desktop.click. By default the
desktop adapter captures a window screenshot immediately before the click and a
second window screenshot immediately after the click by reusing
desktop.screenshot. The click result returns the before/after screenshot
artifact ids and evidence ids under visualVerification, so the gateway can
register the images through the existing command-result artifact path and
operators can compare the click effect without trusting a bare input dispatch
acknowledgement.
180.C.13.07 adds desktop.emergency_stop through
capability:desktop-emergency-stop. The host executor now serializes desktop
fallback commands behind a desktop-only queue, keeps desktop.emergency_stop
out of that queue, and cancels matching queued and running desktop fallback
commands for either the active session or the whole device. Running desktop
commands receive an AbortSignal; desktop.screenshot forwards it to
screencapture, and desktop.click checks it before screenshots and before
Core Graphics input dispatch. The stop result reports the interrupted queued and
running command ids for audit.
180.C.13.12 adds desktop.type through capability:desktop-type. The command
requires the target app/window to be focused and allowlisted, verifies Screen
Recording and Accessibility grants, detects the active macOS keyboard input
source, reports QWERTY/AZERTY/Dvorak/Colemak family plus ANSI/ISO/JIS physical
keyboard shape when available, and emits Unicode keyboard events so
IME/composition and non-US layouts are not forced through US-QWERTY keycodes.
180.C.13.13 adds stable multi-display targeting through
desktop.display.list. The host reports each macOS display with a Core-Graphics
UUID-backed desktop-display:<uuid> stable id, current screencapture index,
direct display id, name, bounds, pixel size, scale factor,
primary/built-in/mirrored flags, and rotation. desktop.screenshot display
targets may now use stableId, uuid, directDisplayId, or name selectors;
the host resolves that selector to the current display index immediately before
capture, so rearranging displays does not silently retarget a saved workflow.
180.C.13.14 adds desktop.clipboard.capture through
capability:desktop-clipboard-capture. The host reads the macOS system
pasteboard with AppKit NSPasteboard, accepts plain text only, enforces
byte/character limits, runs builtin and command-supplied redaction patterns, and
writes only the redacted text as a text/plain audit artifact. The result
returns pasteboard changeCount, advertised pasteboard types, raw and redacted
SHA-256 hashes, redaction metadata, artifact/evidence references, and optional
redacted text for session notes. This gives operators a deterministic path for
copying visible error text into the session without treating OCR guesses as
facts.
Desktop mutating commands carry compensating-action metadata because macOS
desktop input has no native rollback. desktop.window.focus, desktop.click,
desktop.type, and desktop.emergency_stop declare protocol-owned
compensating_action_id metadata and currently use manual_remediation_only:
refocus the reviewed window, review click before/after evidence before applying
click-back or app-specific remediation, undo/remediate typed text through the
target app's reviewed path, and review interrupted session state after emergency
stop. See
docs/domains/bellona/extras/remote-control/desktop-compensating-actions.md
for the binding catalog and future drag/key requirements.
Desktop Fallback Selection Policy#
Desktop fallback is the last-resort control surface. Agents and operators must prefer typed adapters, domain APIs, or high-level automation that can inspect and act on structured state before using screenshot-and-input control.
Use desktop fallback only when all of these conditions are true:
- The requested work cannot be completed through an available Blender, Unreal, browser, file, process, or domain adapter.
- The target app/window is visible, selected explicitly, currently focused, and allowlisted by app name, title fragment, or window id.
- The command is bounded to a visible UI action such as observing a window, focusing a known window, clicking a known coordinate, or handling a modal that no typed adapter can reach.
- Required macOS TCC grants, Bellona control permissions, gateway policy, operator approvals, audit metadata, screenshot evidence, and emergency stop are in the command path.
- Coordinates come from a current screenshot, stream frame, or window inventory record and are normalized before input dispatch.
Use the Blender adapter instead of desktop fallback for Blender scene reads, object creation, material/edit operations, imports, exports, render setup, animation, file mutation, undo checkpoints, or any operation where the Blender addon or bridge can report structured state. A Blender viewport being visible is not enough reason to click through the UI when the adapter can perform or verify the operation.
Use the Unreal adapter instead of desktop fallback for Unreal Editor project state, map or actor queries, content import, placement, Sequencer, play-in-editor state, renders, plugin diagnostics, builds, or editor mutations once the Unreal plugin/adapter supports the action. Desktop fallback may only cover visible UI gaps such as dismissing a non-scriptable dialog after the Unreal route has exhausted structured options.
Use the browser adapter instead of desktop fallback for navigation, DOM or accessibility snapshots, screenshots, downloads/uploads, form interactions, and managed-profile lifecycle when Playwright/CDP can drive the page. Real browser profiles, password-manager surfaces, credential prompts, and untrusted page instructions remain denied unless a later policy explicitly unlocks them.
Desktop fallback must not be used for arbitrary shell execution, arbitrary Blender Python, Unreal console commands, secret or credential entry, financial or publishing actions, OS security prompts, real profile credential flows, destructive project/file changes, or any hidden privileged path. If fallback is used, the command reason must state why the typed adapter path was unavailable and the result must include the relevant audit and visual evidence.
180.C.13.10 adds a remote desktop fallback CLI smoke:
pnpm nx desktop:fallback-remote-smoke @bellona/remote-host
The smoke starts an ephemeral Remote Gateway and Remote Host, registers the
desktop fallback adapter, dispatches desktop.window.focus,
desktop.screenshot, and desktop.click through the gateway-host command path,
approves the required desktop fallback approval requests, verifies the click's
before/after screenshot references, registers screenshot and click verification
artifacts with the gateway, and prints audit and timeline evidence. The default
mode uses deterministic in-process desktop backends so CI can prove routing,
approvals, artifact registration, visual-verification references, and audit
behavior without injecting real macOS input. Pass -- --live-macos on a
configured MacBook with Screen Recording and Accessibility grants to exercise
the native Swift helpers against a real focused window.
Blender Loopback Discovery#
180.C.09.01 adds a real Blender adapter registration helper alongside the
walking-skeleton fake adapter. createRemoteHostBlenderAdapterRegistration()
discovers the repository's existing local Blender control surfaces as loopback
candidates:
libs/bellona/blender/python/bellona_addon/server.py, the Blender addon WebSocket server onlocalhost:9876apps/bellona/bridge-blender/src/main.ts, the bridge-blender loopback service onlocalhost:9001/blender
The helper validates the resulting adapter and capability with
@bellona/remote-protocol and only accepts localhost, 127.0.0.1, or ::1.
Candidates such as 0.0.0.0, LAN addresses, or internet-routable hosts are
rejected before registration, so the remote host never exposes the Blender addon
or bridge as a public control port.
The discovered adapter exposes a host-side health command:
- capability id:
capability:blender-adapter-health - routed command:
blender.adapter.health
The health command reports whether Blender is installed or missing, whether the
addon or bridge is reachable, Blender and addon versions when available,
connection state, endpoint metadata, and the active .blend file path when the
addon provides it. The scene-query capability remains degraded until the
read-only scene-info route is implemented, so discovery and health do not enable
scene control by themselves.
180.C.09.04 adds the read-only scene-info route:
- capability id:
capability:blender-scene-info - routed command:
blender.scene.info
When the local addon exposes scene.info, the host queries it over the
loopback-only WebSocket endpoint and validates the response with
RemoteBlenderSceneInfoSchema from @bellona/remote-protocol. When Blender or
the addon is unavailable, the route returns the protocol mock scene-info fixture
with fallback metadata instead of failing the command; later integration and
hardware smoke tasks replace that fallback with broader coverage.
180.C.09.07 adds an optional local Blender smoke command:
pnpm nx blender:scene-info-smoke @bellona/remote-host
The smoke command looks for BELLONA_BLENDER_EXECUTABLE, then a standard macOS
Blender install, then blender on PATH. If Blender is present, it launches
Blender in background mode, creates and reopens a tiny fixture .blend, calls
the addon scene.info handler, and validates the JSON with
RemoteBlenderSceneInfoSchema. If Blender is absent, it exits successfully with
a skipped summary unless --required or BELLONA_BLENDER_SMOKE_REQUIRED=1 is
set.
The two-MacBook development runbook for the read-only Blender MVP is
docs/domains/bellona/extras/remote-control/blender-read-only-mvp-second-macbook.md.
Use that runbook when the gateway runs on the operator MacBook and the real
Blender adapter runs on the controlled MacBook.
180.C.09.10 adds an agent/CLI smoke command for the full remote path:
pnpm nx blender:scene-info-remote-smoke @bellona/remote-host
The remote smoke starts an ephemeral gateway, starts an outbound host with the
real Blender adapter registration, dispatches blender.scene.info through the
gateway command dispatcher, validates RemoteBlenderSceneInfoSchema, and prints
timeline/audit evidence. It accepts --require-live-addon when the run should
fail instead of using the protocol fallback fixture.
180.C.10.07 adds an optional local Blender mutation smoke command:
pnpm nx blender:create-primitive-smoke @bellona/remote-host
The primitive smoke uses the same Blender lookup order as the scene-info smoke.
When Blender is available, it launches background Blender, creates and reopens a
small fixture .blend, captures scene-info before the mutation, calls the addon
object.create_primitive handler, captures scene-info again, and verifies the
object count increased by one with the created object selected and linked to the
expected material. It also writes a rollback note: in --background mode
Blender cannot execute the editor undo operator, so the smoke restores the saved
fixture and verifies the created object is absent afterward. If Blender is
absent, it exits with a skipped summary unless --required,
BELLONA_BLENDER_SMOKE_REQUIRED=1, or
BELLONA_BLENDER_MUTATION_SMOKE_REQUIRED=1 is set.
180.C.10.08 adds a CLI smoke for mutation timeline visibility:
pnpm nx blender:create-primitive-remote-smoke @bellona/remote-host
The remote primitive smoke starts an ephemeral gateway and host, dispatches
blender.object.create_primitive, and prints the mutation result alongside the
gateway audit entry types and command timeline events. By default it uses a
deterministic in-process primitive provider so the timeline path can run without
a live Blender addon. Pass --live-addon to route the mutation through the
configured local addon endpoint instead.
180.C.17.01 extends the same adapter path with protocol-owned Blender file
commands:
blender.file.openblender.file.saveblender.file.save_asblender.file.pack_resourcesblender.file.recover_last
These commands only run when the active discovery source is the local Bellona
Blender addon. The Remote Host resolves every command path against
BELLONA_PROJECT_ROOT or process.cwd(), refuses paths outside that root,
blocks open and recover_last when the current file is dirty unless the
command explicitly allows unsaved changes, and emits before/after file snapshot
evidence through RemoteBlenderFileMutationResultSchema. The addon now also
serves file.get_path and file.is_modified so the host can enforce those
checks without shell fallback.
180.C.17.02 adds the first protocol-owned Blender object mutation family on
top of the same addon transport:
blender.object.deleteblender.object.renameblender.object.duplicateblender.object.parentblender.object.set_transformblender.object.set_visibility
These commands share a single object-mutation capability, run only against the
local Bellona Blender addon, and always wrap the addon mutation with
before/after blender.scene.info evidence. The addon must create an explicit
undo checkpoint before each mutation and return structured object identifiers,
relationship or transform deltas when relevant, and the committed undo metadata
that the host normalizes into RemoteBlenderObjectMutationResultSchema.
180.C.17.03 extends the same host path with Blender collection coverage:
blender.collection.hierarchyblender.collection.createblender.collection.move_objectblender.collection.set_visibilityblender.collection.set_renderability
The read-only hierarchy query normalizes addon collection trees into
RemoteBlenderCollectionHierarchyResultSchema, including parent-child
relationships, object membership, viewport visibility, and render visibility.
The four collection mutations share a collection-mutation capability, always
capture before/after blender.scene.info evidence, require addon-created undo
checkpoints, and normalize into RemoteBlenderCollectionMutationResultSchema.
The Blender scene client now reads collection hierarchy through this canonical
query instead of issuing unsupported collection detail commands.
180.C.17.04 adds Blender material query and mutation coverage:
blender.material.semantic_searchblender.material.create_principledblender.material.assignblender.material.set_parameterblender.material.bind_texture
The read-only semantic-search path normalizes addon material matches into
RemoteBlenderMaterialSemanticSearchResultSchema, including deterministic
scores, matched terms/features, and assigned-object context. The four material
mutations share a material-mutation capability, always wrap the addon mutation
with before/after blender.scene.info evidence, require addon-created undo
checkpoints, and normalize into RemoteBlenderMaterialMutationResultSchema. The
Blender JS client now routes principled material creation, assignment, parameter
updates, and core texture bindings through these canonical commands instead of
relying on unsupported raw addon verbs.
180.C.17.05 adds canonical Blender asset import coverage:
blender.asset.import
The Remote Host only accepts allowlisted asset paths under
BELLONA_PROJECT_ROOT for this command, verifies the source extension matches
the requested format, records a hashed source-file provenance artifact, wraps
the addon mutation with before/after blender.scene.info evidence, and
normalizes the result into RemoteBlenderAssetImportResultSchema. The addon now
handles GLB/GLTF, FBX, OBJ, USD/USDZ, Alembic, image textures, and audio
references through asset.import, while the legacy raw file.import path
continues to delegate to the same implementation for bridge compatibility.
180.C.17.06 adds canonical Blender asset export coverage:
blender.asset.export
The Remote Host only accepts allowlisted export destinations under
BELLONA_PROJECT_ROOT, verifies the addon-reported output hashes against the
actual exported bytes, registers transfer-ready audit-export artifacts for
every exported file, wraps the addon export with before/after
blender.scene.info evidence, and normalizes the result into
RemoteBlenderAssetExportResultSchema. The addon now handles GLB/GLTF, FBX,
OBJ, USD, Alembic, image sequences, and packaged .blend exports through
asset.export, while the legacy raw file.export path delegates to the same
implementation for bridge compatibility.
180.C.17.07 adds canonical Blender semantic selector coverage:
blender.semantic_selector.query
The Remote Host routes this read-only selector query through the local Bellona
Blender addon and normalizes it into
RemoteBlenderSemanticSelectorQueryResultSchema. The addon resolves fixed
selector presets for emissive objects, selected rigs, large static props,
collection membership, and materials missing textures, while preserving
deterministic ranking and resolved collection metadata for downstream clients.
180.C.17.08 adds deterministic golden-scene coverage in
src/blender-adapter.test.ts for exact blender.scene.info, object rename,
duplicate/undo-checkpoint, material assignment, collection move, asset import,
asset export, and file save-as round trips. The suite pins before/after scene
states, evidence-reference ids, transfer ids, file hashes, and file snapshot
metadata in normal CI without claiming live Blender editor signoff.
180.C.17.09 documents the required hardware/headless verification split for
the broader Blender production command surface in
docs/domains/bellona/extras/remote-control/blender-production-command-hardware-verification.md.
Use that note to decide which commands can be proven in background Blender,
which still need a live editor session, and what evidence file must be recorded
before the stage closes.
180.C.17.10 closes the Stage 17 gate with deterministic
gateway-host-adapter-audit coverage in src/blender-adapter.test.ts for
blender.scene.info, object rename, collection hierarchy and move, material
assign and semantic search, semantic selectors, file.open, file.save,
file.save_as, file.pack_resources, file.recover_last, asset import, and
asset export. The corresponding MAC-HOST-01 evidence bundle is recorded in
docs/domains/bellona/extras/remote-control/evidence/180.C.17.09/2026-04-23-MAC-HOST-01-blender-production-commands.md,
including headless scene.info and primitive smokes plus live remote
--require-live-addon / --live-addon proofs for the Bellona addon path.
180.C.18.01 adds canonical Blender modifier-stack mutation coverage:
blender.modifier.addblender.modifier.configureblender.modifier.reorderblender.modifier.set_viewport_enabledblender.modifier.set_render_enabledblender.modifier.apply
The Remote Host now advertises a dedicated modifier-mutation capability, wraps
every modifier mutation with before/after blender.scene.info evidence, and
records before/after modifier-stack snapshot artifacts so replay and audit
consumers can see exact stack order and visibility changes. The addon returns a
required rollback note plus an undo checkpoint for every modifier mutation, and
the JS Blender clients now route modifier configuration and viewport/render
toggles through these canonical command names instead of unsupported raw verbs.
180.C.18.02 adds canonical Blender Geometry Nodes macro coverage:
blender.geometry_nodes.list_macrosblender.geometry_nodes.apply_macro
The Remote Host now advertises dedicated Geometry Nodes query and mutation
capabilities, exposes a deterministic macro catalog for scatter, cable runs,
kitbash arrays, modular facades, terrain dressing, and procedural prop layout,
and validates every compiled authoring plan with @bellona/blender-agent before
execution. The mutation path captures before/after blender.scene.info
evidence, before/after modifier-stack snapshots, per-plan audit artifacts, and
an undo-backed rollback note while the addon executes only the deterministic raw
geometry_nodes.* tree-edit and apply commands needed by the compiled plans.
180.C.18.03 adds canonical Blender mesh edit macro coverage:
blender.mesh_edit.list_macrosblender.mesh_edit.apply_macro
The Remote Host now advertises dedicated mesh-edit query and mutation
capabilities, exposes a deterministic catalog for bevel, extrude, inset, merge
by distance, normal recalculation, UV unwrap, decimate, and triangulate, and
enforces per-macro selection-domain preconditions before normalizing results.
The mutation path captures before/after blender.scene.info evidence plus
before/after mesh-selection snapshot artifacts, while the addon executes only
the deterministic raw mesh.* edit commands required for each macro and returns
an undo-backed rollback note for every mutation.
Rollback and undo behavior for the primitive mutation MVP is documented in
docs/domains/bellona/extras/remote-control/blender-primitive-rollback-and-undo.md.
The 180.C.10 safe mutation closure evidence is recorded in
docs/domains/bellona/extras/remote-control/blender-safe-mutation-mvp-closure.md.
Command Execution#
When the gateway sends a command.dispatch message, the host executor emits
protocol-valid progress events for accepted, started, running progress, and the
terminal lifecycle state. Completed, failed, cancelled, and timed-out commands
produce a protocol-valid command.result message back to the gateway.
Unexpected executor failures are reported as protocol-valid command.error
messages so the gateway can reject the host event without losing command
correlation. The health payload exposes commands.activeCount for local
diagnostics without exposing command arguments or signed host tokens.
Policy Preflight Stub#
Until the real policy package is added, the host runs a conservative local
preflight named remote-host-known-command-policy-preflight-stub. It only
allows commands advertised by the current adapter registry and denies unknown
command, adapter, or capability targets before adapter routing. Denials return
protocol-valid command.result messages with status: "denied" and
error.code: "policy.denied".
Shutdown Cleanup#
Host shutdown marks readiness not-ready, cancels active commands, closes the
gateway connection, stops in-process adapters, closes the health server, emits
final lifecycle events, flushes logs, and then closes the logger. In-process
adapters are marked blocked after stop so local diagnostics cannot report them
as available during teardown.
Local Startup#
BELLONA_REMOTE_HOST_HEALTH_PORT=4107 BELLONA_REMOTE_HOST_LOG_LEVEL=debug pnpm nx start @bellona/remote-host
curl -fsS http://127.0.0.1:4107/health
curl -fsS http://127.0.0.1:4107/ready
Expected health output is a JSON payload with status: "healthy". Expected
readiness output is a JSON payload with status: "ready" and checks.config,
checks.adapters, checks.gatewayConfiguration, checks.gatewayConnection,
checks.identity, and checks.shuttingDown. If the selected identity store is
missing or invalid, the adapter registry is empty, or the gateway connection is
not yet connected, the health server still starts for diagnostics, but readiness
returns 503.
Local Gateway Smoke#
Use this flow from the repository root to run the real walking-skeleton host against the local gateway.
Terminal 1 starts the gateway:
BELLONA_REMOTE_GATEWAY_PORT=4097 BELLONA_REMOTE_GATEWAY_LOG_LEVEL=debug pnpm nx start @bellona/remote-gateway
Terminal 2 creates an explicit development identity file fixture using the protocol device fixture and the same development signing helper as the gateway, then starts the host against that gateway:
export BELLONA_REMOTE_HOST_IDENTITY_FILE=/tmp/bellona-remote-host.identity.dev.json
pnpm exec tsx --eval "
import { mkdirSync, writeFileSync } from 'node:fs';
import { dirname } from 'node:path';
import { remoteDeviceFixture } from '@bellona/remote-protocol';
import { BELLONA_REMOTE_GATEWAY_DEVELOPMENT_HOST_TOKEN_SIGNING_SECRET } from './apps/bellona/remote-gateway/src/config.ts';
import { createHmacRemoteGatewayHostTokenAuthenticator } from './apps/bellona/remote-gateway/src/host-token.ts';
const credentials = createHmacRemoteGatewayHostTokenAuthenticator({
now: () => new Date('2026-04-22T00:00:00.000Z'),
signingSecret: BELLONA_REMOTE_GATEWAY_DEVELOPMENT_HOST_TOKEN_SIGNING_SECRET,
tokenTtlMs: 90 * 24 * 60 * 60 * 1000
}).issueHostToken({
device: remoteDeviceFixture,
deviceKeyId: 'device-key:studio-macbook-air-development'
});
mkdirSync(dirname(process.env.BELLONA_REMOTE_HOST_IDENTITY_FILE), { recursive: true });
writeFileSync(
process.env.BELLONA_REMOTE_HOST_IDENTITY_FILE,
JSON.stringify(
{
schemaVersion: 1,
storage: 'development-file',
keychainReplacementTask: '180.C.16.01',
device: remoteDeviceFixture,
credentials,
createdAt: '2026-04-22T00:00:00.000Z',
updatedAt: '2026-04-22T00:00:00.000Z',
metadata: { owner: 'local-development-smoke' }
},
null,
2
)
);
"
BELLONA_REMOTE_HOST_GATEWAY_URL=ws://127.0.0.1:4097/v1/hosts/connect \
BELLONA_REMOTE_HOST_HEALTH_PORT=4098 \
BELLONA_REMOTE_HOST_IDENTITY_STORAGE=development-file \
BELLONA_REMOTE_HOST_LOG_LEVEL=debug \
pnpm nx start @bellona/remote-host
Terminal 3 checks readiness:
curl -fsS http://127.0.0.1:4097/ready
curl -fsS http://127.0.0.1:4098/ready
curl -fsS http://127.0.0.1:4098/health
The gateway readiness payload should report status: "ready". The host
readiness payload should report status: "ready", checks.identity: "loaded",
checks.adapters: "ok", and checks.gatewayConnection: "connected". The host
health payload should include two adapters, zero active commands, and the
connected gateway state.
Expected gateway logs include remote gateway listening and
remote host handshake accepted. Expected host logs include
remote host health server listening, remote host identity loaded, and
remote host gateway handshake accepted.
The gateway does not expose a public HTTP command-dispatch endpoint yet. The
executable command round trips for blender.scene.query, blender.scene.info,
and diagnostic.host.snapshot are covered by src/gateway-connection.test.ts,
which drives the same WebSocket command.dispatch path used by the local
gateway connection.
Verification#
pnpm nx test @bellona/remote-host --verbose
pnpm nx typecheck @bellona/remote-host --verbose
pnpm nx lint @bellona/remote-host --verbose
pnpm nx build @bellona/remote-host --skip-nx-cache --verbose
macOS Packaging#
180.C.16.02 adds the initial signed/notarized packaging plan in
macos-packaging-and-notarization-plan.md
and exposes the typed release contract through
createRemoteHostMacOSPackagingPlan(). The plan covers the Remote Host app
bundle, LaunchAgent plist, desktop helper tools, Blender add-on, Unreal plugin,
and final Developer ID Installer package. It is a release contract only; later
Stage 16 and Stage 26 work implements the actual app bundle, installer,
LaunchAgent registration, helper entitlements, updates, uninstall, and live
notarized hardware evidence.
180.C.26.01, .02, .06, .09, and .14 now also expose the locally
testable macOS host contracts through createMacOSLaunchAgentLifecyclePlan(),
deriveMacOSMenuBarModel(), evaluateMacOSSigningReadiness(),
createMacOSInstallQaMatrix(), evaluateMacOSInstallQaEvidence(), and
evaluateMacOSHostStageGate(). These contracts cover the menu-bar status and
control model, LaunchAgent lifecycle commands, signing readiness, install QA
scenario coverage, canonical UTC millisecond per-scenario QA artifacts, and the
Stage 26 roll-up gate. The evaluators reject malformed Developer ID/notary/Team
ID placeholders, missing QA evidence kinds, incomplete, stale, or non-canonical
timestamp artifact metadata, QA artifacts that do not identify their
scenario/evidence-kind context, non-macOS host runner records, stale or
non-canonical QA run timestamps, generic install-QA operator identities,
artifact identifiers duplicated within or across QA/stage evidence records,
including case-variant duplicates, stale or non-canonical timestamp stage
evidence, stage artifacts that identify the checklist item but not the exact
evidence slot they prove, empty or placeholder macOS runner/operator/artifact
suffixes, generic install-QA summaries without complete per-scenario records or
captured before the scenario evidence they summarize, non-developer acceptance
without a non-developer operator identity or captured before prerequisite Stage
26 evidence, and bare Stage 26 booleans. They do not replace the required live
macOS app, launchd, Developer ID, notarization, install QA, and non-developer
acceptance evidence. See
macos-host-local-contracts.md.
Windows Packaging#
180.C.36.01 through .10 expose the locally testable Windows host contracts
through createWindowsRemoteHostPackagingPlan(),
evaluateWindowsSigningReadiness(), resolveWindowsDesktopStrategy(),
createRemoteHostWindowsPermissionProvider(),
buildWindowsManagedBrowserLaunchPlan(), windowsDefaultDiscoveryCandidates(),
createWindowsUpdateChannelPlan(), buildWindowsDiagnosticBundle(),
deriveWindowsHostRoles(), compareWindowsMacCapabilityParity(), and
evaluateWindowsHostStageGate(). These contracts cover the signed MSI/Windows
Service plan, Authenticode environment validation, DXGI/UIAutomation/SendInput
strategy, Windows permission projection, managed Chrome/Edge launch policy,
managed-profile root/path escape rejection, explicit loopback CDP binding, TCP
port validation, fail-closed launch-time initialUrl rejection so navigation
uses the normal browser.navigate policy path, default DCC/browser discovery
paths, signed update rollback, diagnostic bundle shape, fleet role derivation,
macOS/Windows capability parity, and the Stage 36 evidence gate.
The evaluators reject malformed signing variables, placeholder publisher values,
missing Windows runner evidence, missing or Windows-reused macOS parity-runner
evidence, generic parity summaries without a passing structured comparator
result covering the browser, desktop, and Unreal MVP command anchors, and
missing final operator acceptance, including artifact identifiers duplicated
within or across stage evidence records, even when duplicate IDs differ only by
case. They also require Stage 36 artifacts to identify the checklist item, exact
evidence slot, and concrete non-placeholder run/artifact suffix they prove,
reject stale pre-contract stage evidence, require signing/update evidence from a
WIN-SIGN- runner with a concrete suffix, require host/probe/parity evidence
from WIN-HOST- runners with concrete suffixes, require all Stage 36 evidence
timestamps to use canonical UTC millisecond format, require parity evidence from
a MAC-HOST- runner with a concrete suffix, and require final acceptance from
an operator:windows-acceptance: identity with a concrete suffix captured after
every prerequisite Stage 36 evidence record. They also require signed update
rollback evidence to follow the signed MSI/service lifecycle record and parity
evidence to follow the Windows capability records it compares. They do not
replace the required live Windows MSI build/install, service lifecycle run,
DXGI/input probes, UAC/Defender/Smart App Control checks, real app discovery,
diagnostic collection, cross-host parity run, or final operator acceptance
evidence. See
windows-host-local-contracts.md.
Signed Updates#
180.C.16.03 adds the initial signed update channel and rollback contract in
remote-host-update-channel-and-rollback-plan.md.
createRemoteHostUpdatePlan() documents the channel policy, while
verifyRemoteHostSignedUpdateManifest() verifies Ed25519 signatures, manifest
freshness, channel eligibility, required macOS artifacts, rollback metadata, and
adapter compatibility for the Remote Host package, Blender add-on, Unreal
plugin, and desktop helper. Live update delivery and rollback drills remain
blocked until the production macOS app shell, installer, LaunchAgent repair, and
Sparkle-compatible delivery work in later Stage 16 and Stage 26 tasks.