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.
bellonaCLI invocation. The examples below use thebellonabin 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#
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#
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#
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#
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.
-
Mint a pairing code on the gateway (codes live for
BELLONA_REMOTE_GATEWAY_PAIRING_CODE_TTL_MS, default 10 min). -
Redeem it from the host operator's side with the CLI:
bashbellona 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. -
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:
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:
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.
- Stop the processes. Ctrl-C the gateway, host, and Control Room (each
handles SIGINT/SIGTERM with a graceful drain —
registerGracefulShutdownin the gateway/hostmain.ts). - Revoke the device so the host can never reconnect:
bellona remote devices revoke <deviceId> --reason "decommission". - Remove local identity / state files:
- Host dev identity:
~/.oshun/bellona/remote-host.identity.dev.json(path fromBELLONA_REMOTE_HOST_IDENTITY_FILE). On macOS the production identity is in the Keychain under serviceBellona Remote Host— remove that Keychain item too. - Gateway persistent store: the file at
BELLONA_REMOTE_GATEWAY_STORE_FILEif you set one (otherwise state is in-memory and gone on exit). - Host gateway pin: the file written by
FileRemoteHostGatewayPinStore.
- Host dev identity:
- 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.