# Bellona Remote Control — User & Operator Guide (180.C.29.02)

Practical setup and day-to-day operation of the Remote Creative Control Plane:
two-MacBook LAN, cloud (Hetzner / AWS), pairing, permissions, the per-tool
adapters (Blender, Unreal, browser), the Control Room, approvals, takeover,
replay, and uninstall.

Conventions: commands are run with **pnpm** from the repo root unless noted; the
operator CLI binary is `bellona` (`@bellona/cli`). The gateway listens on
**`4070`** by default (`apps/bellona/remote-gateway/src/config.ts`).

> **Honest scope.** This guide describes the real software in this repo. Steps
> that need a *second physical Mac*, the macOS **Keychain / TCC** permission
> system, code-signing/notarization, or a cloud account are called out as such —
> they cannot be exercised on a Linux CI box. For a fully local round-trip on any
> machine, see the [Quickstart](./quickstart.md).
>
> **`bellona` CLI invocation.** The examples below use the `bellona` bin name for
> readability. In a fresh repo checkout the compiled bin does not yet resolve its
> workspace deps standalone — run the CLI from source instead:
> `npx tsx apps/bellona/cli/src/index.ts remote …` (see
> [Quickstart §2](./quickstart.md)). The verbs and flags are identical.

---

## 1. Topologies at a glance

```
A) Two-MacBook LAN          B) Cloud (Hetzner / AWS)
                            
  Agent Mac  ──LAN/WSS──▶     Agent / Control Room ──WSS──▶  Cloud Gateway (TLS edge)
  ┌─────────┐               ┌──────────────┐                 ┌───────────────────────┐
  │ gateway │               │ operator     │                 │ Caddy/ALB :443        │
  │  :4070  │◀── host ──┐   │ browser/CLI  │                 │   → gateway :4070     │
  └─────────┘  /v1/hosts/│  └──────────────┘                 └──────────┬────────────┘
       ▲       connect    │                                              │ /v1/hosts/connect
  Control Room            │        Studio Mac (controlled) ──outbound────┘   (host dials OUT;
  (operator)        Studio Mac (controlled host)                              no inbound port
                    Blender / Unreal / Chrome                                 on the Mac)
```

In **both** topologies the **host dials out** to the gateway over a single
WebSocket (`/v1/hosts/connect`); the controlled machine never opens an inbound
port and keeps engine/debug ports loopback-bound. The cloud case just puts the
gateway behind a TLS edge on the internet.

---

## 2. Two-MacBook LAN setup

You need two machines on the same LAN: an **agent Mac** (runs the gateway +
Control Room) and a **studio Mac** (the controlled host, runs Blender/Unreal/
Chrome). Either machine can host the gateway; this layout keeps it next to the
operator.

### 2.1 On the agent Mac — start the gateway

```bash
pnpm install
# Bind to the LAN so the studio Mac can reach it (default is loopback 127.0.0.1):
BELLONA_REMOTE_GATEWAY_HOST=0.0.0.0 \
BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET="$(openssl rand -hex 32)" \
  pnpm --filter @bellona/remote-gateway start
```

`start` runs `tsx src/main.ts` → `startRemoteGateway()`. Health:
`curl http://localhost:4070/health`. Keep the signing secret — the host token is
HMAC'd with it.

### 2.2 On the agent Mac — start the Control Room

```bash
pnpm --filter @bellona/control-room dev:enabled
```

`dev:enabled` runs `VITE_BELLONA_CONTROL_ROOM_ENABLED=true vite --host 127.0.0.1`
(the Control Room is feature-flagged off otherwise — see
`apps/bellona/control-room/src/config.ts:CONTROL_ROOM_FEATURE_FLAG`). Open the URL
Vite prints.

### 2.3 On the studio Mac — start the host

```bash
pnpm install
BELLONA_REMOTE_HOST_GATEWAY_URL="ws://<agent-mac-lan-ip>:4070/v1/hosts/connect" \
  pnpm --filter @bellona/remote-host start
```

`start` runs `tsx src/main.ts` → `startRemoteHost()`. The host loads its identity
(macOS Keychain by default — `BELLONA_REMOTE_HOST_IDENTITY_STORAGE=macos-keychain`;
use `development` for a file-backed dev identity), then dials the gateway and
registers its adapters. Discovery via mDNS (`_bellona-host._tcp`) is supported,
but **discovery is not trust** — the host is only authorized after pairing.

---

## 3. Cloud setup (Hetzner / AWS)

Both reference deployments run the same gateway image off the public internet
except through a TLS edge. They are documented in full elsewhere; this section is
the operator summary.

### 3.1 Hetzner (single node, Docker Compose)

`deploy/bellona-remote/hetzner/docker-compose.prod.yml`. Caddy terminates TLS on
80/443; the gateway (`4070`) sits on a private Docker network; coturn serves
STUN/TURN. The Hetzner Cloud firewall opens **only** 80/443 + the TURN ports
(3478/5349 + relay range) — not 4070/5432/9000. Provide
`BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET`, a domain, and the
TURN/Postgres/MinIO secrets in `.env`, then bring the stack up. Step-by-step:
**[hetzner-reference-deployment.md](./hetzner-reference-deployment.md)**.

### 3.2 AWS (ALB + Fargate, Terraform)

`deploy/bellona-remote/aws/*.tf`. An internet-facing ALB (TLS, 75 s idle timeout,
sticky sessions so a host's WSS tunnel pins to one task) fronts an ECS Fargate
gateway service on `4070` in private subnets; RDS Postgres + ElastiCache Redis are
reachable only from the gateway security group; a coturn EC2 with an Elastic IP
serves TURN; secrets come from Secrets Manager. `terraform apply`, then point the
host's `BELLONA_REMOTE_HOST_GATEWAY_URL` at `wss://<gateway-domain>/v1/hosts/connect`.
Step-by-step: **[aws-reference-deployment.md](./aws-reference-deployment.md)**. A
WireGuard/Tailscale private-network alternative is in
**[tailscale-wireguard-private-network.md](./tailscale-wireguard-private-network.md)**.

---

## 4. Pairing a host

Pairing binds a host's device identity to the gateway with a one-time code.

1. **Mint a pairing code** on the gateway (codes live for
   `BELLONA_REMOTE_GATEWAY_PAIRING_CODE_TTL_MS`, default 10 min).
2. **Redeem it from the host operator's side** with the CLI:

   ```bash
   bellona remote --gateway-url http://<gateway-host>:4070 \
     pair --code <CODE> --device '<device-json>'
   ```

   This calls `POST /v1/pairing/exchange`
   (`apps/bellona/remote-gateway/src/pairing-exchange.ts`), which issues the host
   an HMAC host token. The host presents that token in its WebSocket handshake
   (`gateway-connection.ts:sendHandshake`); the gateway verifies it
   (`host-token.ts`) before accepting the connection.

3. **First-trust pinning.** The host pins the gateway's certificate fingerprint on
   first connect (`gateway-pinning.ts:evaluateGatewayPin`). A later *changed* key
   is refused as a possible MITM until an authorized re-pin.

Confirm the device appears: `bellona remote devices list`. To **revoke** a device
(block + disconnect): `bellona remote devices revoke <deviceId> --reason "…"`, or
`bellona remote unpair <deviceId>`.

---

## 5. Permissions

Two distinct layers — don't confuse them:

### 5.1 OS host permissions (what the Mac/PC grants)

The host runtime detects OS-level grants and surfaces gaps. On macOS these are
**TCC** grants the operator approves in *System Settings → Privacy & Security*:

| Capability | macOS authority | Needed for |
| --- | --- | --- |
| Screen Recording / Capture | macOS TCC | streaming, `desktop.screenshot` |
| Accessibility / Synthetic Input | macOS TCC | `desktop.type`, `desktop.click` |
| Application Automation | macOS TCC (Automation) | launching/controlling apps |
| Files & Folders | macOS TCC (Files) | file adapter access |

The runtime never auto-allows: a granted capability is projected as
**`requires-approval`**, not `allowed` — the gateway still gates each command
(`host-runtime/src/permission-provider.ts:hostPermissionReportToRemotePermissions`).
Missing required grants make the device report `missing`; the Control Room Devices
view surfaces it. The full cross-platform model (and how Linux/Windows differ) is
in [Host Permission Abstraction](./host-permission-abstraction.md).

### 5.2 Command permissions (what the agent is allowed to do)

Independent of OS grants, every command is policy-checked
(`policy.ts:evaluateRemoteCommandPolicy`): the device must grant the *permission
scopes* the command's verbs imply (`project.write`, `desktop.input`,
`browser.profile.real`, `file.write`, `command.execute.destructive`, …). A scope
the device does not grant ⇒ the command is denied or routed to approval. Org
admins can layer presets on top — `organization-template.ts` ships
`solo-creator`, `small-studio`, `enterprise-studio`, `education-lab`,
`local-only-private`, and `review-only` (the last hard-forbids any mutation).

---

## 6. Working with the tools

### 6.1 Blender

The Blender adapter (`apps/bellona/remote-host/src/blender-adapter.ts`) speaks
typed commands — `blender.scene.query` (read-only), `blender.create_primitive`,
plus mesh-edit / camera-lighting / geometry-nodes / rigging / render / simulation
families. Read-only queries need no approval; mutating commands carry a rollback
strategy and (for destructive ones) a dry-run plan. Python is preflighted and
redacted (`blender-python-preflight.ts`, `blender-python-redaction.ts`). Quick
local check on any box: `pnpm --filter @bellona/remote-host blender:scene-info-remote-smoke`
(falls back to deterministic scene output when no live Blender). Undo/rollback
detail: [blender-primitive-rollback-and-undo.md](./blender-primitive-rollback-and-undo.md).

### 6.2 Unreal

The Unreal adapter (`unreal-adapter.ts`) exposes `unreal.project.info`,
`unreal.world.query`, `unreal.actor.spawn`, `unreal.map.{list,open,save,create}`,
`unreal.actor.{select,set_transform,set_property,attach,destroy}`,
`unreal.blueprint.call_function`, `unreal.material.set_parameter`. Raw escape
hatches `unreal.console.execute` and `unreal.python.exec` are **blocked** by the
adapter. Architecture: [unreal-plugin-architecture.md](./unreal-plugin-architecture.md).

### 6.3 Browser

The browser adapter (`browser-adapter.ts`) drives a **managed** Chrome/Chromium
profile by default (`browser.launch.managed`, `browser.navigate`,
`browser.click_element`, `browser.type_into`, `browser.snapshot`,
`browser.screenshot`, tab/nav controls, `browser.download` / `browser.upload`).
A real **personal** profile requires explicit grants (`browser.profile.grant` /
`browser.use_personal`) and is a `browser.profile.real` scope — credential fields
are blocked from automation. Profile isolation:
[browser-profile-isolation.md](./browser-profile-isolation.md). An optional Chrome
extension (`@bellona/remote-extension`) shows an automation indicator while a
session is active.

---

## 7. The Control Room: approvals, takeover, replay

Open the Control Room (§2.2) and pick a session. The relevant panels
(`apps/bellona/control-room/src/App.tsx:createWorkspaceViews`):

### 7.1 Approvals

The **Approvals** queue (`approval-queue.ts`) lists pending requests with the
policy explanation (which scopes/risk triggered it) and the projected cost of the
next step. Decide with **Approve once**, **Approve for session**, or **Deny**;
these map to `decideApproval` on the gateway. Pending requests auto-expire after
`BELLONA_REMOTE_GATEWAY_APPROVAL_REQUEST_TTL_MS` (default 60 s). From the CLI:

```bash
bellona remote approve list --status pending
bellona remote approve grant <requestId> --by <participantId>
bellona remote approve deny  <requestId> --by <participantId> --reason "…"
```

### 7.2 Takeover

The operator can pause, resume, stop, or **take over** a session
(`operator-controls.ts` — the `ControlRoomOperatorActionId` set:
`pause | resume | stop | takeover | release-takeover | …`). Takeover requests/
grants flow through the gateway session lifecycle
(`session-lifecycle.ts:requestTakeover` / `grantTakeover` / `takeoverSession`,
`POST /v1/sessions/{id}/takeover`). The desktop adapter also honours an
`desktop.emergency_stop` command.

### 7.3 Replay

The **Replay** view (`replay-view.ts`) scrubs a single time axis across six lanes
(`timeline`, `screenshot`, `stream`, `command`, `approval`, `artifact`) with
frame-accurate seek, so you can reconstruct exactly what happened around any
moment. The replay bundle is built from the hash-chained audit + registered
artifacts; verify or export the underlying chain with:

```bash
bellona remote audit query --session <sessionId>
bellona remote audit export --session <sessionId> --format jsonl -o session.audit.jsonl
```

(`GET /v1/timeline`, `GET /v1/audit/export` — the export is self-verifying.)
Audit-bundle anatomy: [session-timeline-and-audit-bundle.md](./session-timeline-and-audit-bundle.md).

---

## 8. Uninstall / teardown

The control plane is processes + a few local files; there is no system service to
remove unless you installed a packaged build.

1. **Stop the processes.** Ctrl-C the gateway, host, and Control Room (each
   handles SIGINT/SIGTERM with a graceful drain — `registerGracefulShutdown` in
   the gateway/host `main.ts`).
2. **Revoke the device** so the host can never reconnect:
   `bellona remote devices revoke <deviceId> --reason "decommission"`.
3. **Remove local identity / state files:**
   - Host dev identity: `~/.oshun/bellona/remote-host.identity.dev.json` (path from
     `BELLONA_REMOTE_HOST_IDENTITY_FILE`). On macOS the production identity is in
     the **Keychain** under service `Bellona Remote Host` — remove that Keychain
     item too.
   - Gateway persistent store: the file at `BELLONA_REMOTE_GATEWAY_STORE_FILE` if
     you set one (otherwise state is in-memory and gone on exit).
   - Host gateway pin: the file written by `FileRemoteHostGatewayPinStore`.
4. **Cloud:** Hetzner — `docker compose -f docker-compose.prod.yml down -v`;
   AWS — `terraform destroy`. The macOS app uninstall (for a notarized packaged
   build) is covered by
   [macos-packaging-and-notarization-plan.md](./macos-packaging-and-notarization-plan.md).

For a curated end-to-end operator walkthrough see
[operator-workflow-blender-browser-mvp.md](./operator-workflow-blender-browser-mvp.md);
for runbooks (incidents, rollback) see
[mvp-alpha-operations-runbooks.md](./mvp-alpha-operations-runbooks.md).
