# Bellona Remote Control — Local Dev Quickstart (180.C.29.13)

**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](./architecture.md) ·
[Developer Guide](./developer-guide.md) · [User & Operator Guide](./user-operator-guide.md).

---

## 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.

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

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

```json
{
  "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`):

1. `createRemoteGatewayApp(...)` started on an ephemeral port (the real gateway).
2. `gateway.hostTokenAuthenticator.issueHostToken(...)` minted an HMAC host token.
3. `createRemoteHostApp(...)` started and **dialled the gateway over WebSocket**
   (`ws://127.0.0.1:<port>/v1/hosts/connect`), authenticating with that token.
4. `gateway.commandDispatcher.dispatchCommand(...)` ran the policy check, appended
   to the **hash-chained audit log** (`computeRemoteAuditEntryHash`), and sent a
   `command.dispatch` to the host.
5. The host's command executor routed it to the Blender adapter, which returned a
   scene-info result; the host replied `command.result`.
6. `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* `RemoteBlenderSceneInfo` when 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-addon` to 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`:

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

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

```bash
curl -s http://localhost:4070/health
```

### Terminal 2 — the host

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

```bash
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.json` declares a
> `bellona` bin and a `build` (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.js` fails with `ERR_MODULE_NOT_FOUND`. Running the source
> through `tsx` (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)

```bash
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 `remoteControlGateway` is
> wired** into the server (`stdio-server.ts`). Launching `bellona-mcp-gateway`
> with 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](./developer-guide.md).

---

## 5. Verify nothing is broken

No Nx needed (call vitest directly from each package dir — avoids the worktree
duplicate-project issue):

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

```bash
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**. |
