Status: 180.C.16.07 alpha runbook pack.
Runbook date: 2026-04-23.
These runbooks consolidate the current Phase 180 operating procedures for MVP alpha hardening. They do not mark any live hardware, cloud, WebRTC, plugin, or uninstall behavior as production-certified. Each runbook names the automated or manual evidence that must be attached when the procedure is exercised.
Sources Reviewed#
docs/domains/bellona/extras/remote-control/blender-read-only-mvp-second-macbook.mddocs/domains/bellona/extras/remote-control/hetzner-reference-deployment.mddocs/domains/bellona/extras/remote-control/aws-reference-deployment.mddocs/domains/bellona/extras/remote-control/session-timeline-and-audit-bundle.mddocs/domains/bellona/extras/remote-control/macos-packaging-and-notarization-plan.mddocs/domains/bellona/extras/remote-control/network-impairment-test-plan.mddocs/domains/bellona/extras/remote-control/security-regression-test-plan.mddocs/domains/bellona/extras/remote-control/performance-budget-test-plan.mdapps/bellona/remote-host/README.mdapps/bellona/remote-gateway/README.md
Common Evidence Rules#
For every live run, capture:
- repository commit SHA on every participating machine
- operator, host, gateway, and cloud environment labels
- absolute timestamps with timezone for start, failure, remediation, and finish
- relevant
/health,/ready, timeline, audit, artifact, and command IDs - redacted logs only; never paste host tokens, API keys, cookies, passwords, or personal filesystem paths into evidence
- final status:
passed,failed,blocked, orskipped-with-reason
When a runbook says "stop," do not continue the scenario until the failed check is understood and documented.
Two-MacBook LAN Setup#
Use this when MAC-OP-01 runs the gateway and MAC-HOST-01 runs Remote Host
plus local adapters on the same trusted LAN.
Prerequisites:
- same repository commit on both machines
pnpm installcompleted on both machines- gateway, host, and adapter ports reserved locally
- no inbound command, browser, Blender, Unreal, or MCP port exposed on
MAC-HOST-01 - optional
jq,lsof,nc, andcurl
Procedure:
-
On
MAC-OP-01, find the LAN address:bashexport BELLONA_OPERATOR_LAN_IP="$(ipconfig getifaddr en0 || ipconfig getifaddr en1)" -
Start the gateway with a durable first-stage store:
bashmkdir -p .local/bellona BELLONA_REMOTE_GATEWAY_HOST=0.0.0.0 \ BELLONA_REMOTE_GATEWAY_PORT=4097 \ BELLONA_REMOTE_GATEWAY_STORE_FILE=.local/bellona/remote-gateway.lan.json \ BELLONA_REMOTE_GATEWAY_LOG_LEVEL=debug \ pnpm nx start @bellona/remote-gateway -
From
MAC-OP-01, verify gateway readiness:bashcurl -fsS "http://${BELLONA_OPERATOR_LAN_IP}:4097/health" | jq . curl -fsS "http://${BELLONA_OPERATOR_LAN_IP}:4097/ready" | jq . -
On
MAC-HOST-01, point the host at the LAN gateway:bashexport BELLONA_REMOTE_HOST_GATEWAY_URL="ws://${BELLONA_OPERATOR_LAN_IP}:4097/v1/hosts/connect" export BELLONA_REMOTE_HOST_PAIRING_EXCHANGE_URL="http://${BELLONA_OPERATOR_LAN_IP}:4097/v1/pairing/exchange" -
Verify local adapters before starting a host-to-gateway run. For Blender:
bashpnpm nx blender:scene-info-smoke @bellona/remote-host -- --required -
Verify the routed path with the available smoke:
bashpnpm nx blender:scene-info-remote-smoke @bellona/remote-host -
Confirm timeline and audit continuity from
MAC-OP-01:bashcurl -fsS "http://${BELLONA_OPERATOR_LAN_IP}:4097/v1/timeline?limit=200" | jq .
Evidence to attach:
- LAN IP used by
MAC-OP-01 - gateway
/healthand/readyJSON - host connection/device ID and adapter capability report
- routed smoke command ID, result ID, timeline event count, and audit entry types
- proof that Blender/Unreal/browser/debug ports are loopback-only on
MAC-HOST-01
Stop conditions:
- any controlled-host service binds to a LAN address unexpectedly
- gateway readiness is not
ready - timeline lacks command receipt, dispatch, and completion/denial records
Cloud Gateway Setup#
Use this when the gateway runs on Hetzner, AWS, or another trusted cloud edge and Remote Host connects outbound over WSS 443.
Prerequisites:
- DNS name, TLS certificate, and public HTTPS path are ready
- gateway process binds only to localhost behind the reverse proxy or load balancer
- public firewall/security group exposes only approved ingress such as 80/443
- host token and pairing secrets are injected through a secret manager or local environment file, never cloud-init user data
- TURN is documented as enabled, disabled, or blocked; do not claim TURN relay without a later WebRTC smoke
Procedure:
-
Deploy the gateway at the documented commit.
-
Verify public readiness:
bashcurl -fsS https://bellona-gateway.example.com/health | jq . curl -fsS https://bellona-gateway.example.com/ready | jq . -
Verify the local gateway bind on the cloud host. For a Linux VM:
shss -ltnp | grep ':4070' curl -fsS http://127.0.0.1:4070/health | jq . -
Inspect recent gateway and proxy/load-balancer logs. For systemd/Caddy:
shsudo journalctl -u bellona-remote-gateway --since "10 minutes ago" --no-pager sudo journalctl -u caddy --since "10 minutes ago" --no-pager -
Configure the Remote Host:
envBELLONA_REMOTE_HOST_GATEWAY_URL=wss://bellona-gateway.example.com/v1/hosts/connect BELLONA_REMOTE_HOST_PAIRING_EXCHANGE_URL=https://bellona-gateway.example.com/v1/pairing/exchange
Evidence to attach:
- provider, region, VM/instance type, OS image, and commit SHA
- DNS record and certificate identifier without private keys
- firewall/security group rules proving the internal gateway port is not public
- public
/healthand/readyJSON - recent gateway/proxy logs with secrets redacted
- host-facing WSS URL and pairing URL
- TURN status and the reason if TURN is not yet exercised
Stop conditions:
- internal gateway port is publicly reachable
/readyis not ready- logs expose secrets
- host requires inbound connectivity
Permissions Troubleshooting#
Use this when desktop fallback, screenshot capture, window list/focus, click, or type commands report missing macOS permissions.
Checks:
- Screen Recording maps to
desktop.observe - Accessibility maps to
desktop.input - granted TCC state does not bypass gateway policy or operator approval
- missing/unknown TCC state must be advertised as denied host permissions with remediation text
Procedure:
-
Run host diagnostics and capture the macOS permission report:
bashpnpm nx desktop-fallback-remote-smoke @bellona/remote-host -
On
MAC-HOST-01, open System Settings > Privacy & Security. -
Grant Screen Recording to the signed Bellona Remote Host or current dev terminal host process for observe/screenshot flows.
-
Grant Accessibility only when input/focus/type/click flows are being tested.
-
Restart the host process after changing TCC grants.
-
Rerun the diagnostic smoke and compare permission decisions.
Evidence to attach:
- before/after permission report
- command IDs blocked by missing permissions
- exact TCC grant changed
- confirmation that gateway policy still reports
requires-approvalfor desktop input after the macOS grant
Stop conditions:
- desktop input is allowed without an Accessibility grant
- screenshot/window capture proceeds without Screen Recording
- a test bypasses gateway policy or approval because TCC is granted
Plugin Repair#
Use this when Blender addon or Unreal plugin detection fails.
Blender repair:
-
Confirm the addon is linked into the installed Blender version:
bashBLENDER_VERSION=<installed-major-minor> BLENDER_ADDONS_DIR="${HOME}/Library/Application Support/Blender/${BLENDER_VERSION}/scripts/addons" ls -la "${BLENDER_ADDONS_DIR}/bellona_addon" -
Ensure the addon host is
localhostand port is9876. -
Confirm the port is loopback-only:
bashlsof -nP -iTCP:9876 -sTCP:LISTEN nc -vz 127.0.0.1 9876 -
Run:
bashpnpm nx blender:scene-info-smoke @bellona/remote-host -- --required
Unreal repair:
-
Confirm the checked-in plugin descriptor exists:
bashtest -f libs/bellona/unreal/plugin/BellonaUnrealEditor/BellonaUnrealEditor.uplugin -
Confirm the project has the plugin installed or symlinked according to the Unreal plugin architecture doc.
-
Confirm the Remote Control endpoint remains localhost-only.
-
Run the available deterministic remote smoke:
bashpnpm nx unreal:readonly-remote-smoke @bellona/remote-host --skip-nx-cache --verbose
Evidence to attach:
- Blender version, addon path, addon endpoint, and local smoke output
- Unreal Engine version, project path, plugin descriptor path, and smoke output
- proof that addon/plugin/debug endpoints are not LAN-exposed
Stop conditions:
- Blender addon binds to a LAN address
- Unreal Remote Control or plugin transport is exposed beyond localhost
- repair requires arbitrary Python, shell execution, console commands, or policy bypass
Stream Failure#
Use this when screenshot-first stream status, WebRTC loopback, same-LAN media, or TURN media fails.
Procedure:
-
Classify the stream path: screenshot placeholder, same-LAN WebRTC, or TURN.
-
Record stream descriptor ID, session ID, device ID, and command ID.
-
Check gateway timeline for stream evidence and command state:
bashcurl -fsS "${GATEWAY_URL}/v1/timeline?sessionId=${SESSION_ID}&kind=stream,command&limit=200" | jq . -
If same-LAN or TURN is in scope, collect ICE candidate type, selected route, startup timing, disconnect reason, and teardown status.
-
If screenshot fallback is in scope, verify artifact registration, redaction status, and capture timing.
-
Mark the stream degraded or failed; do not silently fall back without audit evidence.
Evidence to attach:
- stream descriptor and timeline records
- startup duration from the performance budget plan
- selected path: screenshot, direct ICE, or TURN relay
- degradation reason and user-visible state
- teardown/cleanup result
Stop conditions:
- media or screenshots continue after stop/revocation
- stream evidence lacks audit/timeline records
- TURN is claimed without a TURN-only relay smoke
Revocation#
Use this when an operator removes trust from a device or suspects host compromise.
Procedure:
- Pause or stop active sessions for the device if possible.
- Revoke the device through the gateway device revocation service or the operator surface that wraps it.
- Confirm the device snapshot status is
blocked. - Confirm active host connections were disconnected with reason
device-revoked. - Attempt a read-only diagnostic command and confirm policy denies it.
- Attempt host reconnect and confirm it is rejected or remains blocked.
- Export the session/device audit bundle.
Evidence to attach:
- device ID, revocation reason, revoking participant ID
- audit entry type
device.revoked - disconnected connection IDs
- denied command ID after revocation
- failed reconnect evidence
- audit bundle path/checksum
Stop conditions:
- blocked device can dispatch any command
- host can reconnect without re-pairing/explicit unblock
- revocation audit entry is missing
Audit Export#
Use this when a session needs review, incident evidence, release evidence, or handoff to another operator.
Prerequisites:
- gateway started with
BELLONA_REMOTE_GATEWAY_STORE_FILE - session is stopped, paused, or otherwise quiescent when an exact export is required
jq,shasum, andzipinstalled
Procedure:
-
Capture the timeline:
bashSESSION_ID=session:example-remote-control GATEWAY_URL=http://127.0.0.1:4097 STORE_FILE=.local/bellona/remote-gateway.store.json EXPORT_DIR=.local/bellona/audit-export/${SESSION_ID} mkdir -p "${EXPORT_DIR}" curl -fsS "${GATEWAY_URL}/v1/timeline?sessionId=${SESSION_ID}&limit=1000" \ > "${EXPORT_DIR}/timeline.json" -
Build the audit bundle from the durable store using the procedure in
session-timeline-and-audit-bundle.md. -
Generate a SHA-256 manifest and ZIP archive.
-
Register the bundle as an
audit-exportartifact. -
Store the bundle in the release/incident evidence location.
Evidence to attach:
- timeline query URL
- bundle file path or object-store URI
- manifest SHA-256
- registered artifact ID
- redaction status
Stop conditions:
- gateway store is missing when durable audit is required
- exported bundle contains plaintext secrets
- manifest does not verify
Uninstall#
Use this when removing the Remote Host, LaunchAgent, helpers, addon/plugin payloads, local identity, or development fixtures from a Mac.
Current status:
- signed installer/uninstaller and LaunchAgent lifecycle are planned in Stage 26; this runbook is a controlled development cleanup path
- do not delete Keychain identity or audit evidence unless the operator request explicitly includes identity/evidence removal
Procedure:
-
Stop active sessions and export needed audit bundles.
-
Stop the development Remote Host process.
-
If a LaunchAgent exists, unload it:
bashlaunchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.oshun.bellona.remote-host.plist -
Remove development LaunchAgent and helper payloads only after recording their paths:
bashrm -f ~/Library/LaunchAgents/com.oshun.bellona.remote-host.plist -
Remove development identity fixture files only when they are not needed:
bashrm -f ~/.oshun/bellona/remote-host*.identity.dev.json -
Remove Blender addon symlinks created by the development runbook:
bashBLENDER_VERSION=<installed-major-minor> rm -f "${HOME}/Library/Application Support/Blender/${BLENDER_VERSION}/scripts/addons/bellona_addon" -
Remove Unreal project plugin symlinks or copied plugin payloads created by the repair/install run; leave repository source files intact.
-
Revoke the device in the gateway if the host should no longer be trusted.
-
Optionally reset macOS TCC grants through System Settings when the operator wants permission cleanup.
Evidence to attach:
- sessions stopped and audit bundle exported
- LaunchAgent unload result
- removed file paths
- identity retention/removal decision
- device revocation result when applicable
- final
ps,launchctl, andlsofchecks showing no Remote Host process or unintended local listener remains
Stop conditions:
- audit evidence is deleted before export
- Keychain identity is deleted without explicit instruction
- repository plugin source is removed instead of only installed/symlinked payloads