Eve library

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

Guide

Revision 1

On this page

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.

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). The verbs and flags are identical.


1. Topologies at a glance#

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

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. A WireGuard/Tailscale private-network alternative is in 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.

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.

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.

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


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.

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