# Bellona Blender Read-Only MVP Second MacBook Runbook

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`](./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`](./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`.
