Runbook date: 2026-04-22
Scope: 180.C.09.09
This runbook documents the current development flow for running the Phase 180 Blender read-only MVP with a Bellona Remote Gateway on the operator MacBook and a Bellona Remote Host plus Blender on a second MacBook. It keeps the controlled MacBook outbound-only to the gateway and keeps the Blender addon loopback-only.
The current gateway does not expose a public command-dispatch HTTP API yet.
blender.scene.info is routed and covered by automated gateway/host tests, and
180.C.09.10 adds a CLI smoke that queries the full gateway-host-adapter path
with an ephemeral gateway and outbound host. Use this runbook to bring up the
two-MacBook runtime and collect readiness evidence; use the local Blender smoke
and remote-path CLI smoke to verify the scene-info payload and routing.
Current Support Matrix#
| Surface | Current support |
|---|---|
| Gateway | Same-LAN HTTP/WebSocket service with host handshake, signed development host token validation, timeline. |
| Host transport | Outbound WebSocket from controlled MacBook to gateway. No inbound host command port is required. |
| Host adapter | Real Blender adapter can be registered through the development host wrapper below. |
| Blender addon endpoint | localhost:9876 on the controlled MacBook only. Do not bind it to a LAN address. |
| Scene-info command | blender.scene.info, read-only, protocol-validated, automated through gateway and host tests. |
| CLI scene-info query | pnpm nx blender:scene-info-remote-smoke @bellona/remote-host starts an ephemeral full path. |
| Public HTTP command API | Not exposed yet; later client/API work must not bypass gateway policy or audit. |
Prerequisites#
Use these roles:
MAC-OP-01: operator MacBook. Runs the Bellona Remote Gateway.MAC-HOST-01: controlled second MacBook. Runs Blender and the Bellona Remote Host.
Both machines need:
- The same repository checkout and commit.
- Node.js 20 or newer.
- pnpm 10.25.0 from the repo toolchain.
- Dependencies installed from the repo root.
The controlled MacBook also needs:
- Blender installed at
/Applications/Blender.app/Contents/MacOS/Blender, orBELLONA_BLENDER_EXECUTABLEpointing to the Blender executable. - The Bellona Blender addon source from
libs/bellona/blender/python/bellona_addon. - The Python
websocketspackage available in Blender's Python environment if the UI addon server is used.
Optional tools for evidence review:
jqlsofnc
Network Rules#
- The gateway may bind to the operator MacBook LAN interface for this development run.
- The controlled MacBook must initiate the connection to the gateway.
- Do not expose Blender, the Blender addon, or the Remote Host health server on the LAN.
- Keep the Blender addon host preference at
localhostand port9876. - Keep
BELLONA_REMOTE_HOST_HEALTH_HOSTat the default127.0.0.1unless a later signed host package adds a supervised diagnostics channel.
Operator MacBook: Start The Gateway#
From the repository root on MAC-OP-01, pick a LAN address reachable from the
controlled MacBook:
ipconfig getifaddr en0 || ipconfig getifaddr en1
Export it for later commands:
export BELLONA_OPERATOR_LAN_IP=<operator-lan-ip>
Start the gateway on the LAN interface with a first-stage store so timeline and audit state survive process restarts:
mkdir -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.second-macbook.json \
BELLONA_REMOTE_GATEWAY_LOG_LEVEL=debug \
pnpm nx start @bellona/remote-gateway
In another terminal on MAC-OP-01, confirm the gateway is healthy and ready:
curl -fsS "http://${BELLONA_OPERATOR_LAN_IP}:4097/health" | jq
curl -fsS "http://${BELLONA_OPERATOR_LAN_IP}:4097/ready" | jq
Expected readiness:
status: "ready"checks.config: "ok"checks.deviceRegistry: "ok"checks.shuttingDown: false
Controlled MacBook: Install Or Enable The Addon#
From the repository root on MAC-HOST-01, link the addon source into Blender's
user addon directory for the installed Blender version:
BLENDER_VERSION=<installed-major-minor> # example: 4.1 or 5.0
BLENDER_ADDONS_DIR="${HOME}/Library/Application Support/Blender/${BLENDER_VERSION}/scripts/addons"
mkdir -p "${BLENDER_ADDONS_DIR}"
ln -sfn "${PWD}/libs/bellona/blender/python/bellona_addon" \
"${BLENDER_ADDONS_DIR}/bellona_addon"
Open Blender on MAC-HOST-01, enable the Bellona Bridge addon, set its host
to localhost, set its port to 9876, and start the server from the Bellona
sidebar. The addon should report that it is running on localhost:9876.
Do not set the addon host to 0.0.0.0 or a LAN IP. The Remote Host connects to
the addon from the same machine over loopback.
Controlled MacBook: Verify Local Scene Info#
Before connecting to the gateway, verify Blender can produce the canonical scene-info payload locally:
pnpm nx blender:scene-info-smoke @bellona/remote-host -- --required
Expected JSON summary:
status: "passed"activeSceneIdfor the generated fixture sceneobjectCountgreater than zerorenderEngineset by the fixtureselectedObjectIdscontaining the fixture cube
If this command fails because Blender is not found, set:
export BELLONA_BLENDER_EXECUTABLE=/Applications/Blender.app/Contents/MacOS/Blender
If the smoke passes but the UI addon endpoint is not reachable, check that
Blender is still running and that port 9876 is loopback-only:
lsof -nP -iTCP:9876 -sTCP:LISTEN
nc -vz 127.0.0.1 9876
Controlled MacBook: Verify The Full Remote Path CLI#
Run the committed CLI smoke to prove an agent/CLI can query scene info through gateway dispatch, outbound host transport, host command execution, the Blender adapter handler, gateway result routing, timeline, and audit:
pnpm nx blender:scene-info-remote-smoke @bellona/remote-host
This command starts an ephemeral gateway and an ephemeral outbound host in the same process. By default it accepts the protocol fallback fixture when the live addon is not reachable, so it is suitable for CI and development machines without Blender running.
When Blender is open and the Bellona addon server is running on
localhost:9876, require a live addon response:
pnpm nx blender:scene-info-remote-smoke @bellona/remote-host -- --require-live-addon
Expected output includes:
status: "passed"commandId: "command:blender-scene-info-remote-smoke-001"auditEntryTypescontainingcommand.received,command.dispatched, andcommand.completedtimelineEventscontaining command-store progress/result eventsfallback: falsewhen--require-live-addonsucceeds
Controlled MacBook: Create An Explicit Development Identity Fixture#
The public pairing-code creation UI/API is not exposed yet. For this development
run, either pair the Remote Host so it writes credentials into macOS Keychain,
or create an explicit signed development identity fixture using the same gateway
signing helper as the running gateway. Run this from the repository root on
MAC-HOST-01 only when using the fixture path:
If the gateway was started with a custom
BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET, export the same value in
this terminal before generating the identity.
export BELLONA_REMOTE_HOST_IDENTITY_FILE="${HOME}/.oshun/bellona/remote-host.second-macbook.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 now = new Date();
const signingSecret =
process.env.BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET ??
BELLONA_REMOTE_GATEWAY_DEVELOPMENT_HOST_TOKEN_SIGNING_SECRET;
const credentials = createHmacRemoteGatewayHostTokenAuthenticator({
now: () => now,
signingSecret,
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,
displayName: 'Studio MacBook Air - Blender Read-Only MVP'
},
credentials,
createdAt: now.toISOString(),
updatedAt: now.toISOString(),
metadata: {
owner: 'second-macbook-read-only-mvp',
scope: '180.C.09.09',
gateway: process.env.BELLONA_REMOTE_HOST_GATEWAY_URL ?? null
}
},
null,
2
) + '\\n'
);
"
This is development-only fixture storage. Normal host pairing now stores the same device identity, device key id, expiry, and signed host token in macOS Keychain by default.
Controlled MacBook: Start The Real Blender Host#
The default pnpm nx start @bellona/remote-host command still starts the
walking-skeleton fake Blender adapter. For the read-only Blender MVP, start the
host with a development wrapper that registers the real loopback Blender adapter
and the host diagnostics adapter:
mkdir -p .local/bellona
cat > .local/bellona/start-blender-readonly-host.ts <<'TS'
import {
createHostDiagnosticsAdapterRegistration,
createInMemoryRemoteHostAdapterRegistry,
createRemoteHostApp,
createRemoteHostBlenderAdapterRegistration,
} from '../../apps/bellona/remote-host/src/index.ts';
const adapterRegistry = createInMemoryRemoteHostAdapterRegistry({
registerDefaultFakeAdapters: false,
});
adapterRegistry.registerAdapter(createRemoteHostBlenderAdapterRegistration());
adapterRegistry.registerAdapter(
createHostDiagnosticsAdapterRegistration({
listAdapters: () => adapterRegistry.listAdapters(),
listCapabilities: () => adapterRegistry.listCapabilities(),
})
);
const app = createRemoteHostApp({ adapterRegistry });
const stop = (reason: string) => {
void app.stop(reason).then(
() => process.exit(0),
(error) => {
console.error(error);
process.exit(1);
}
);
};
process.once('SIGINT', () => stop('SIGINT'));
process.once('SIGTERM', () => stop('SIGTERM'));
await app.start();
console.log(JSON.stringify({
status: 'started',
health: app.health(),
readiness: app.readiness()
}, null, 2));
TS
Start the host against the operator gateway:
export BELLONA_OPERATOR_LAN_IP=<operator-lan-ip>
export 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"
export BELLONA_REMOTE_HOST_HEALTH_PORT=4098
export BELLONA_REMOTE_HOST_IDENTITY_STORAGE=development-file
export BELLONA_REMOTE_HOST_LOG_LEVEL=debug
pnpm exec tsx .local/bellona/start-blender-readonly-host.ts
Expected host startup output:
status: "started"health.adapters.adapterCount: 2health.adapters.capabilityCount: 4readiness.checks.identity: "loaded"readiness.checks.adapters: "ok"readiness.checks.gatewayConnection: "connected"readiness.status: "ready"
The two adapters are the real adapter:blender-local adapter and the
adapter:host-diagnostics adapter. The four capabilities are
capability:blender-scene-query, capability:blender-adapter-health,
capability:blender-scene-info, and capability:host-diagnostics-snapshot.
Operator MacBook: Confirm Host Registration#
On MAC-OP-01, confirm gateway readiness still passes:
curl -fsS "http://${BELLONA_OPERATOR_LAN_IP}:4097/ready" | jq
Then inspect the gateway store for the connected device snapshot:
jq '.devices[] | {
id,
displayName,
status,
adapterIds: [.adapters[].id],
commandNames: [.capabilities[].commandNames[]]
}' .local/bellona/remote-gateway.second-macbook.json
Expected device evidence:
status: "online"adapterIdsincludesadapter:blender-localcommandNamesincludesblender.scene.infocommandNamesincludesblender.adapter.health- no LAN address is listed for the Blender adapter endpoint
Timeline And Audit Review#
The remote-path CLI smoke prints timeline and audit evidence for its ephemeral gateway run. For a long-running gateway with a durable store, review a scene-info command timeline with:
COMMAND_ID=command:blender-scene-info-route-001
curl -fsS \
"http://${BELLONA_OPERATOR_LAN_IP}:4097/v1/timeline?commandId=${COMMAND_ID}&limit=100" \
| jq '.events[] | {
occurredAt,
kind,
type,
source,
commandId,
deviceId,
auditSequence
}'
Expected command timeline after a successful live query:
command.receivedcommand.dispatchedcommand.resultcommand.completed
Use
session-timeline-and-audit-bundle.md
to export a store-backed audit bundle when the command is part of a signoff
session.
Evidence To Capture#
For the later hardware-gated signoff, record a Markdown evidence file under:
docs/domains/bellona/extras/remote-control/evidence/180.C.09.10/<date>-MAC-HOST-01-blender-scene-info.md
Include:
- operator Mac rig id, macOS version, LAN IP, gateway command, gateway commit
- controlled Mac rig id, macOS version, Blender version, host command, host commit
- addon source path or release id
- confirmation that Blender addon listens only on
localhost:9876 - host readiness JSON with
gatewayConnection: "connected" - gateway store excerpt showing
blender.scene.info - local
blender:scene-info-smokeoutput - remote-path CLI smoke output or live command timeline and audit entries
For the primitive safe-mutation stage, record rollback notes using
blender-primitive-rollback-and-undo.md.
Troubleshooting#
Gateway readiness fails:
- Confirm
BELLONA_REMOTE_GATEWAY_HOST=0.0.0.0and port4097are set. - Check macOS firewall prompts on
MAC-OP-01. - Verify
curl http://127.0.0.1:4097/readylocally before testing LAN access.
Host readiness stays not-ready:
- Confirm
BELLONA_REMOTE_HOST_IDENTITY_FILEpoints to the generated identity. - Confirm
BELLONA_REMOTE_HOST_GATEWAY_URLuses the operator Mac LAN IP. - Check host logs for
remote host gateway handshake accepted. - Check gateway logs for
remote host handshake rejectedand token mismatch details.
Blender scene-info smoke fails:
- Set
BELLONA_BLENDER_EXECUTABLEto the Blender executable path. - Run Blender once normally to clear first-launch prompts.
- Confirm the repository checkout contains
libs/bellona/blender/python/bellona_addon/handlers.py.
Addon endpoint is unreachable:
- Start the Bellona server from the Blender sidebar.
- Keep addon host set to
localhost. - Install
websocketsinto Blender's Python environment if Blender reports it missing. - Verify
nc -vz 127.0.0.1 9876from the controlled MacBook.
Gateway store does not show blender.scene.info:
- Make sure the host was started with
.local/bellona/start-blender-readonly-host.ts, not the default fake-adapter host start command. - Confirm the host startup output reports
capabilityCount: 4.