Eve library

Bellona Blender Read-Only MVP Second MacBook Runbook

Guide

Revision 1

On this page

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, or BELLONA_BLENDER_EXECUTABLE pointing to the Blender executable.
  • The Bellona Blender addon source from libs/bellona/blender/python/bellona_addon.
  • The Python websockets package available in Blender's Python environment if the UI addon server is used.

Optional tools for evidence review:

  • jq
  • lsof
  • nc

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 localhost and port 9876.
  • Keep BELLONA_REMOTE_HOST_HEALTH_HOST at the default 127.0.0.1 unless 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:

bash
ipconfig getifaddr en0 || ipconfig getifaddr en1

Export it for later commands:

bash
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:

bash
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:

bash
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:

bash
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:

bash
pnpm nx blender:scene-info-smoke @bellona/remote-host -- --required

Expected JSON summary:

  • status: "passed"
  • activeSceneId for the generated fixture scene
  • objectCount greater than zero
  • renderEngine set by the fixture
  • selectedObjectIds containing the fixture cube

If this command fails because Blender is not found, set:

bash
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:

bash
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:

bash
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:

bash
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"
  • auditEntryTypes containing command.received, command.dispatched, and command.completed
  • timelineEvents containing command-store progress/result events
  • fallback: false when --require-live-addon succeeds

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.

bash
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:

bash
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:

bash
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: 2
  • health.adapters.capabilityCount: 4
  • readiness.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:

bash
curl -fsS "http://${BELLONA_OPERATOR_LAN_IP}:4097/ready" | jq

Then inspect the gateway store for the connected device snapshot:

bash
jq '.devices[] | {
  id,
  displayName,
  status,
  adapterIds: [.adapters[].id],
  commandNames: [.capabilities[].commandNames[]]
}' .local/bellona/remote-gateway.second-macbook.json

Expected device evidence:

  • status: "online"
  • adapterIds includes adapter:blender-local
  • commandNames includes blender.scene.info
  • commandNames includes blender.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:

bash
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.received
  • command.dispatched
  • command.result
  • command.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:

text
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-smoke output
  • 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.0 and port 4097 are set.
  • Check macOS firewall prompts on MAC-OP-01.
  • Verify curl http://127.0.0.1:4097/ready locally before testing LAN access.

Host readiness stays not-ready:

  • Confirm BELLONA_REMOTE_HOST_IDENTITY_FILE points to the generated identity.
  • Confirm BELLONA_REMOTE_HOST_GATEWAY_URL uses the operator Mac LAN IP.
  • Check host logs for remote host gateway handshake accepted.
  • Check gateway logs for remote host handshake rejected and token mismatch details.

Blender scene-info smoke fails:

  • Set BELLONA_BLENDER_EXECUTABLE to 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 websockets into Blender's Python environment if Blender reports it missing.
  • Verify nc -vz 127.0.0.1 9876 from 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.