Goal: clone → a real command round-trip in ~5 minutes, on any machine (Linux CI box, Intel/Apple Mac, no second computer, no Blender, no Unreal, no cloud).
This walks the whole spine — gateway ↔ host transport, command executor, adapter routing, hash-chained audit, unified timeline — so a new contributor sees the system work end to end without reassembling it from per-package docs. Every command below was run on the Linux dev box; where a step would need a real Mac or a live DCC, the closest local equivalent is given and the difference is stated plainly.
For the bigger picture: Architecture · Developer Guide · User & Operator Guide.
0. Prerequisites#
- Node 20+ and pnpm (the repo's package manager).
- From the repo root:
pnpm install. - (Optional) Docker, only if you want the shared dev infra (Postgres/Redis/ MinIO/Mailpit). The round-trip below needs none of it — the gateway runs an in-memory store by default.
git clone git@github.com:GreyChimp/oshun.git
cd oshun
pnpm install
1. The 60-second round-trip (one command)#
The fastest proof the plane works. This script boots an in-process gateway,
boots an in-process host, issues a real HMAC host token, connects the host to
the gateway over the real /v1/hosts/connect WebSocket, dispatches one real
blender.scene.query command, and prints the result, the gateway's
hash-chained audit-entry types, and the unified timeline:
pnpm --filter @bellona/remote-host blender:scene-info-remote-smoke
Verified output on this box (abridged) — note command.received → dispatched → completed are real audit-log entries, and "fallback": true shows the Blender
adapter gracefully degrading because no live Blender is attached:
{
"status": "passed",
"deviceId": "device:studio-macbook-air",
"commandId": "command:blender-scene-info-remote-smoke-001",
"fallback": true,
"gatewayPort": 46257,
"objectCount": 3,
"renderEngine": "CYCLES",
"auditEntryTypes": ["command.received", "command.dispatched", "command.completed"],
"timelineEvents": [
"audit-log:command.received", "audit-log:command.dispatched",
"command-store:command.progress", "...",
"audit-log:command.completed", "command-store:command.result"
]
}
What just happened (source: apps/bellona/remote-host/scripts/blender-scene-info-remote-smoke.ts):
createRemoteGatewayApp(...)started on an ephemeral port (the real gateway).gateway.hostTokenAuthenticator.issueHostToken(...)minted an HMAC host token.createRemoteHostApp(...)started and dialled the gateway over WebSocket (ws://127.0.0.1:<port>/v1/hosts/connect), authenticating with that token.gateway.commandDispatcher.dispatchCommand(...)ran the policy check, appended to the hash-chained audit log (computeRemoteAuditEntryHash), and sent acommand.dispatchto the host.- The host's command executor routed it to the Blender adapter, which returned a
scene-info result; the host replied
command.result. gateway.timeline.queryTimeline(...)returned the merged audit + command view.
Why this runs with no Blender / no Mac: the real Blender adapter returns a deterministic fallback
RemoteBlenderSceneInfowhen it can't reach a live Blender, so the transport + dispatch + audit spine is exercised for real even on a headless Linux box. Pass--require-live-addonto make it fail instead of falling back (that path needs a real Blender + addon).
Sibling one-command round-trips (same pattern, other adapters)#
All verified to exist as package scripts in
apps/bellona/remote-host/package.json:
pnpm --filter @bellona/remote-host blender:create-primitive-remote-smoke
pnpm --filter @bellona/remote-host browser:managed-remote-smoke
pnpm --filter @bellona/remote-host desktop:fallback-remote-smoke
pnpm --filter @bellona/remote-host unreal:readonly-remote-smoke
pnpm --filter @bellona/remote-host unreal:actor-spawn-remote-smoke
2. The full spine, started by hand (gateway + host + CLI)#
If you'd rather run the long-lived processes yourself (closer to a real
deployment), use three terminals from the repo root. Pick unique ports if
4070/4071 are taken (ss -lnt to check).
Terminal 1 — the gateway#
BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET="$(openssl rand -hex 32)" \
pnpm --filter @bellona/remote-gateway start
Runs tsx src/main.ts → startRemoteGateway(). It listens on HTTP + WebSocket
on :4070. Check it:
curl -s http://localhost:4070/health
Terminal 2 — the host#
BELLONA_REMOTE_HOST_IDENTITY_STORAGE=development \
BELLONA_REMOTE_HOST_GATEWAY_URL="ws://127.0.0.1:4070/v1/hosts/connect" \
pnpm --filter @bellona/remote-host start
Runs tsx src/main.ts → startRemoteHost(). It registers its adapters — the
fake Blender adapter (blender.scene.query), plus the real
blender/browser/unreal/file/desktop adapters and the host-diagnostics /
remote-host-state adapters (adapter-registry.ts) — and dials the gateway.
The host authenticates with an HMAC host token. In a real setup you mint a pairing code on the gateway and redeem it from the host (
bellona remote pair --code …, →POST /v1/pairing/exchange). For the local spine, prefer the §1 one-command script, which mints and injects the token for you with no manual pairing.
Terminal 3 — drive it with the CLI#
Run the CLI from source with tsx (the reliable dev path — see the note below).
Set the gateway URL explicitly — the CLI's built-in default is
http://localhost:4100 (apps/bellona/cli/src/utils/remote-client.ts), which does
not match the gateway's default :4070, so you must point it:
export BELLONA_REMOTE_GATEWAY_URL="http://localhost:4070"
# confirm the verbs (prints the real `bellona remote` help)
npx tsx apps/bellona/cli/src/index.ts remote --help
# inspect the live gateway
npx tsx apps/bellona/cli/src/index.ts remote diagnose
npx tsx apps/bellona/cli/src/index.ts remote devices list
npx tsx apps/bellona/cli/src/index.ts remote sessions list
Every bellona remote verb used here is registered in
apps/bellona/cli/src/commands/remote.ts; the CLI talks to the gateway through
the @oshun/bellona-client SDK (createBellonaRemoteClient).
Why
tsx, not the compiled bin.apps/bellona/cli/package.jsondeclares abellonabin and abuild(tsc) +start(node dist/…), but in a fresh checkout the compiled output keeps bare workspace specifiers (@oshun/bellona-client, …) that Node's ESM loader can't resolve standalone —node dist/…/index.jsfails withERR_MODULE_NOT_FOUND. Running the source throughtsx(which honours the workspace path mappings) is the working dev invocation. A packaged distribution would bundle/resolve those deps; that packaging is not wired in this repo state.
3. See it in the Control Room (optional)#
pnpm --filter @bellona/control-room dev:enabled
Runs VITE_BELLONA_CONTROL_ROOM_ENABLED=true vite --host 127.0.0.1 — the
dev:enabled script is required because the Control Room is feature-flagged off
by default (apps/bellona/control-room/src/config.ts:CONTROL_ROOM_FEATURE_FLAG = VITE_BELLONA_CONTROL_ROOM_ENABLED). Open the URL Vite prints; the Devices,
Session, Timeline, Approvals, and Replay views are the operator surface over the
same gateway.
4. The MCP surface (agent-facing tools) — what's real#
There is a real MCP server, @bellona/mcp-gateway
(libs/bellona/mcp-gateway/src/stdio-server.ts,
bin bellona-mcp-gateway → stdio-cli.js). It exposes a curated tool set —
device.list, session.start, session.stop, blender.scene.info,
blender.create_primitive, browser.navigate, browser.snapshot,
desktop.screenshot (BELLONA_MCP_REMOTE_CONTROL_TOOL_NAMES in
remote-control-tools.ts).
Honest caveat: those tools register only when a
remoteControlGatewayis wired into the server (stdio-server.ts). Launchingbellona-mcp-gatewaywith defaults starts a valid MCP server but exposes no remote-control tools until a gateway is injected — by design (the MCP server is a tool surface over the gateway, not a second authority). For a no-wiring local round-trip, use the CLI (§2) or the §1 script, which need nothing extra. Wiring the MCP server to a live gateway client is covered in Developer Guide §3.
5. Verify nothing is broken#
No Nx needed (call vitest directly from each package dir — avoids the worktree duplicate-project issue):
cd apps/bellona/remote-gateway && npx vitest run src/host-connections.test.ts # gateway↔host WS
cd ../remote-host && npx vitest run src/adapter-registry.test.ts src/command-executor.test.ts
cd ../../../libs/bellona/remote-protocol && npx vitest run src/command.test.ts src/policy.test.ts
All of these pass on the Linux box and exercise the real round-trip path (handshake, dispatch, policy, audit).
6. Optional: the shared dev infra#
You don't need this for the round-trip, but if a later task wants Postgres/Redis/ MinIO:
docker compose -f docker/docker-compose.dev.yml up -d
docker compose -f docker/docker-compose.dev.yml ps
Tear down with down (keep data) or down -v (wipe). The gateway only uses a
real store when you set BELLONA_REMOTE_GATEWAY_STORE_FILE (or a DB URL in a
cloud deployment); by default it is in-memory.
What was verified vs. what needs more#
| Step | Status on the Linux dev box |
|---|---|
§1 blender:scene-info-remote-smoke round-trip |
Ran, passed — real gateway↔host WS, dispatch, hash-chained audit, timeline (fallback: true). |
| §1 sibling smoke scripts | Exist as package scripts (verified in package.json); browser/desktop/unreal fall back like Blender when no live app. |
§2 gateway start / host start / health route |
Real tsx entry points + /health route verified in code. |
| §2 CLI verbs | Ran npx tsx …/cli/src/index.ts remote --help — prints the real verbs. Gateway URL must be set to :4070 (CLI default is :4100). The compiled node dist/… bin does not run standalone in a fresh checkout (ERR_MODULE_NOT_FOUND) — use tsx. |
§3 Control Room dev:enabled |
Real Vite script; gated by the verified feature flag. |
| §4 MCP server | Real package + bin; tools register only with a gateway wired (stated above). |
§1 --require-live-addon, real Blender/Unreal/Chrome, cloud deploy |
Need a real Mac + DCC / browser / cloud account — not exercised here. |