This is the architecture reference for the Bellona Remote Creative Control Plane: the system that lets a trusted Oshun agent drive Blender, Unreal Engine, Chrome/Chromium, and selected desktop workflows on a second machine over the LAN or a cloud tunnel, while an operator watches and approves through the Control Room.
Every claim below maps to code in this monorepo. Module paths are given as
path/to/file.ts:Symbol. For the higher-level decisions behind these shapes see
the ADRs in adr/; for the security posture see
SECURITY-REVIEW.md and
privacy-legal-review.md.
1. Component topology#
The control plane is four long-lived processes plus one shared, authoritative schema package. Nothing trusts a peer it has not cryptographically verified.
┌────────────────────────────────────────────────────────────┐
│ @bellona/remote-protocol (libs/bellona/remote-protocol) │
│ the ONE authoritative wire schema: envelopes, risk classes, │
│ command families, audit chain, policy, transport, security │
└───────────────▲───────────────▲───────────────▲─────────────┘
│ imports │ imports │ imports
operator / agent │ │ │
┌──────────────────┐ HTTP / WS ┌─────┴───────────┐ WSS ┌──────────┴────────┐
│ Control Room │◀────── :4070 ─────▶│ Remote Gateway │◀──────▶│ Remote Host │
│ apps/bellona/ │ REST + timeline │ apps/bellona/ │ /v1/ │ apps/bellona/ │
│ control-room │ │ remote-gateway │ hosts/ │ remote-host │
│ (React/Vite) │ │ (the authority) │ connect│ (on the Mac/PC) │
└──────────────────┘ └─────────────────┘ └─────────┬─────────┘
▲ ▲ │ in-process
│ SDK / CLI / MCP │ HTTP ▼
┌───────┴───────────────────────────────┐ │ ┌────────────────────────┐
│ @oshun/bellona-client (SDK, 29.04) │───────┘ │ Adapters: blender / │
│ bellona remote … (CLI, 29.06) │ │ browser / unreal / file │
│ @bellona/mcp-gateway (MCP tools) │ │ / desktop / diagnostics │
└────────────────────────────────────────┘ └────────────────────────┘
│ wires
▼
@bellona/host-runtime (26.16): platform-neutral
permission / process / screen-capture contract
| Component | Package | Entry point | Role |
|---|---|---|---|
| Remote Protocol | @bellona/remote-protocol |
libs/bellona/remote-protocol/src/index.ts |
The authoritative, versioned wire schema. Every other component imports it; none redefines a wire shape. |
| Remote Gateway | @bellona/remote-gateway |
apps/bellona/remote-gateway/src/main.ts:startRemoteGateway |
The privileged authority: pairing, host-token auth, policy, approvals, durable hash-chained audit, command dispatch, session lifecycle, timeline. |
| Remote Host | @bellona/remote-host |
apps/bellona/remote-host/src/main.ts:startRemoteHost |
Runs on the controlled machine. Connects out to the gateway, registers adapters, executes authorized commands, enforces host-local deny + gateway pinning. |
| Control Room | @bellona/control-room |
apps/bellona/control-room/src/main.tsx |
Operator web UI: device roster, session page, live timeline, approval queue, stream, replay, diff, cost. |
| SDK | @oshun/bellona-client |
libs/bellona/client/src/remote/client.ts:createBellonaRemoteClient |
Typed programmatic client (used by the CLI and by agents). |
| CLI | @bellona/cli (bellona bin) |
apps/bellona/cli/src/commands/remote.ts:remoteCommand |
bellona remote … operator/automation commands over the SDK. |
| MCP gateway | @bellona/mcp-gateway |
libs/bellona/mcp-gateway/src/stdio-server.ts:connectBellonaMcpGatewayStdioServer |
Exposes a curated subset of remote-control operations as MCP tools/resources for agent runtimes. |
| Browser extension | @bellona/remote-extension |
apps/bellona/remote-extension/src/background.ts |
Optional Chrome extension for managed-profile browser automation with an automation indicator. |
Why standalone gateway + host rather than reusing an existing bridge: see
adr/ADR-0001-standalone-remote-gateway-and-host.md.
2. The protocol: envelopes, risk classes, command families#
The protocol package is the contract. The three load-bearing concepts:
2.1 The command envelope#
RemoteCommandEnvelopeSchema (libs/bellona/remote-protocol/src/command.ts) is a
strict Zod object. Beyond the obvious fields (id, sessionId, target,
arguments) it carries the governance fields that make a command auditable and
safe:
actorChain— the full delegation chain (operator → orchestrator → specialist → adapter), modelled byRemoteActorChainSchema(libs/bellona/remote-protocol/src/actor.ts). This is what the audit log and watermark bind a command to.riskClass— one ofread-only | safe-mutation | destructive | privileged(RemoteCommandRiskClassSchema).approvalRequired,idempotencyKey,timeoutClass+timeoutMs,metadata.rollbackStrategy,metadata.dryRunPlanId.
The schema is not a passive container — its superRefine block enforces
invariants at parse time:
- A
destructiveorprivilegedcommand must setapprovalRequired=true. - A
safe-mutation/destructive/privilegedcommand must declare ametadata.rollbackStrategy(one ofRemoteRollbackStrategySchema:undo_stack | snapshot_restore | compensating_action | manual_remediation_only). - A
destructive/privilegedcommand must declare dry-run support (metadata.dryRunSupported=true+metadata.dryRunPlanId). - A mutating
browser.*/desktop.*command must name its protocol-owned compensating action (browser-compensating-actions.ts/desktop-compensating-actions.ts). timeoutMsmay not exceed the maximum for itstimeoutClass.target.commandNamemust start withtarget.namespace + ".".
An ill-formed or under-governed command therefore cannot even be constructed — the failure is at the boundary, not deep in execution.
2.2 Risk classes drive everything downstream#
read-only → no approval, no rollback, no dry-run. (e.g. blender.scene.query)
safe-mutation → rollback strategy required. (e.g. blender.object.move)
destructive → approval + rollback + dry-run required. (e.g. file.snapshot.restore)
privileged → approval + rollback + dry-run required. (e.g. shell / arbitrary code)
2.3 Command families (namespaces)#
REMOTE_COMMAND_NAMESPACE (libs/bellona/remote-protocol/src/namespaces.ts)
defines the 13 namespaces. Command names are namespace.verb[.noun]:
| Namespace | Examples | Served by adapter |
|---|---|---|
device |
device registration / status | gateway |
session |
session.start, session.stop |
gateway |
stream |
stream start/stop/switch | gateway + host |
agent |
agent.readiness |
host state adapter |
state |
state.snapshot |
host state adapter |
blender |
blender.scene.query, blender.create_primitive, … |
blender adapter |
unreal |
unreal.project.info, unreal.actor.spawn, unreal.map.open, … |
unreal adapter |
browser |
browser.navigate, browser.click_element, browser.profile.grant, … |
browser adapter |
desktop |
desktop.screenshot, desktop.type, desktop.emergency_stop |
desktop adapter |
file |
file.grant.create, file.transfer.to_host, file.snapshot.restore |
file adapter |
process |
process launch | host runtime |
approval |
approval.request, approval.decide |
gateway |
diagnostic |
diagnostic.host.snapshot |
host diagnostics adapter |
Protocol version negotiation: RemoteProtocolVersionSchema and the host
handshake (supportedProtocolVersions) let a host and gateway agree on a
MAJOR.MINOR.PATCH version; BELLONA_REMOTE_PROTOCOL_VERSION is 0.1.0.
3. Trust boundaries#
The plane is built defence-in-depth. No single check is the whole story; a command must clear all of these gates before it has any effect.
agent/operator → [SDK/CLI/MCP] → HTTP/WS → ┌── GATEWAY ───────────────────────────┐
│ 1. host-token auth (HMAC) │
│ 2. device registry (blocked? revoked?)│
│ 3. evaluateRemoteCommandPolicy │ → allowed | requires-approval | denied
│ 4. approval gate (operator decision) │
│ 5. append to hash-chained audit log │
└──────────────┬───────────────────────┘
│ command.dispatch (WSS)
┌── HOST ──────▼───────────────────────┐
│ 6. gateway pinning (MITM defence) │
│ 7. policy preflight (re-check) │
│ 8. host-local deny (operator's rules) │ ← can only DENY, never grant
│ 9. sensitive-path guard (default-deny) │
│ 10. adapter executes; redaction on out │
└────────────────────────────────────────┘
3.1 Identity & transport trust#
- Host token (HMAC). The host authenticates to the gateway with a signed
token in the WebSocket handshake. The gateway side is
apps/bellona/remote-gateway/src/host-token.ts(HMAC authenticator,BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET); the host presents it inapps/bellona/remote-host/src/gateway-connection.ts:sendHandshake. - Device keys & clone detection.
device-key.tsmodels signing-key generations with bounded overlap windows and clone signals (RemoteDeviceCloneSignalSchema: concurrent endpoints, replayed nonce, stale monotonic counter). - Gateway pinning (host side).
apps/bellona/remote-host/src/gateway-pinning.ts:evaluateGatewayPinpins the gateway's leaf-cert fingerprint at first trust and refuses a changed key (possible MITM) unless an authorized re-pin rotates it. Backed byFileRemoteHostGatewayPinStore(atomic temp-then-rename writes). - Discovery is not trust. mDNS discovery (
transport.ts, service_bellona-host._tcp) only finds an endpoint; a candidate isunverifieduntil its advertised fingerprint matches the trusted registry (RemoteHostDiscoveryVerificationSchema).
3.2 Authorization gates#
- Command policy.
evaluateRemoteCommandPolicy(libs/bellona/remote-protocol/src/policy.ts) derives the required permission scopes from the command name verbs + risk class + namespace (e.g. adeleteverb addscommand.execute.destructive; adesktopobserve verb addsdesktop.observe; abrowserreal-profile request addsbrowser.profile.real) and resolves them against the device's granted permissions, returningallowed | requires-approval | deniedwith the exact scope lists. It also computes the dry-run requirement. - Host-local deny (last line).
apps/bellona/remote-host/src/host-local-deny.ts:enforceHostLocalDenyruns after gateway authorization and can only deny — by namespace, command name/prefix, risk class, target device, argument path/origin, or the sensitive-path guard.applyHostLocalDenyAfterAuthorizationcomposes them with AND logic: a gateway "yes" can be downgraded to "no", never the reverse. - Sensitive-path default-deny.
sensitive-paths.ts:isSensitiveProtectedPathis a pure, platform-aware classifier that refuses~/.ssh, password/credential stores, browser secrets, the macOS keychain, OS settings, and anything outside the declared project root.
3.3 Confidentiality & accountability#
- Redaction.
redaction-engine.ts:RemoteRedactionEngine/redactRemoteSurfacedeterministically scrubs secrets and PII across surfaces (logs, screenshot text, traces, browser content, command payloads, file paths) recognising OpenAI/GitHub/AWS/Slack/Google keys, JWTs, private keys, emails, phone numbers, home paths. - Watermarking.
watermark.ts:buildStreamWatermark/verifyStreamWatermarkapplies a dual watermark — a visible overlay (session id + attribution token) and a cryptographic HMAC-SHA256 over the full actor chain — so a leaked clip is attributable to an exact operator and delegation chain. - Hash-chained audit.
audit-chain.ts:computeRemoteAuditEntryHash/verifyAuditChainis the single authoritative tamper-evident chain (each entry hashes its content + the previous hash).assertHighTrustCommandChainedfail-loud-refuses to leave a high-trust command unchained. - Right to erasure.
erasure.tsreconciles an append-only audit with user deletion via cryptographic erasure: personal data is AEAD-encrypted with per-subject keys; erasure appends a tombstone (chain stays verifiable) and destroys the subject key, rendering ciphertext unrecoverable (verifyAuditIntegrityAfterErasure). - Incidental consent.
incidental-consent.ts:resolveIncidentalSubjectDispositionis fail-closed: a subject captured in a stream (video-call window, bystander, visible document) is redacted unless an explicit, in-scope, unexpired grant exists.
3.4 Organization governance#
organization-control.ts:evaluateOrganizationControl— admin policy across 7 surfaces (device-pairing, session-start, stream-access, risky-approval, audit-export, mcp-client, external-browser-provider), deny-by-default.organization-template.ts:resolveOrganizationPolicyTemplate— six presets (solo-creator,small-studio,enterprise-studio,education-lab,local-only-private,review-only) each bundling controls + spend budgets + retention/residency.review-onlyhard-forbids mutating commands (assertReviewOnlyCommandAllowed).
The detailed threat model is
adr/ADR-0002-remote-control-threat-model.md;
the gateway-trust / E2E-encryption stance is
adr/ADR-0003-gateway-trust-and-e2e-encryption-model.md.
4. Transport & protocols (180.C.25.01–03)#
Two link types, one decision function:
- Direct LAN (
direct_lan) — selected only when policy permits it and the LAN host is reachable and verified. - Gateway tunnel (
gateway_tunnel) — the fallback, and the forced path for high-risk command classes (so they always hit the audited authority).
RemoteCommandRouteDecisionSchema (transport.ts) models the choice with the
reasons (direct-lan-allowed-and-reachable, policy-forces-gateway,
lan-host-unreachable, lan-host-unverified, …). The schema refuses to call a
route direct_lan unless directLanPolicyAllowed && lanReachable && lanVerified.
- Discovery: mDNS/DNS-SD service
_bellona-host._tcp(REMOTE_HOST_MDNS_SERVICE_TYPE), TXT records carry protocol version + cert fingerprint + auth scheme. - Resume: when an outbound tunnel drops, the gateway-issued resume token
(
REMOTE_TUNNEL_RESUME_TOKEN_SCHEME = 'bellona-tunnel-resume-v1') lets the host reconnect to the same session without re-pairing — an expired/unknown token forces a re-handshake, never re-pairing. - Idempotency:
RemoteTunnelDedupeEntrySchemakeys duplicate-suppression on the command idempotency key.
The actual sockets live behind injectable seams in the gateway/host services; the
protocol package carries only the wire-visible facts. QUIC/WebTransport was
evaluated and deferred — see
adr/ADR-0007-quic-webtransport-evaluation.md.
5. The Gateway (the authority)#
createRemoteGatewayApp (apps/bellona/remote-gateway/src/app.ts) composes the
in-memory (optionally file-backed) services and serves HTTP + WebSocket on one
port (default 4070).
5.1 Services#
| Service | Factory (apps/bellona/remote-gateway/src/…) |
Responsibility |
|---|---|---|
| Device registry | device-registry.ts:createInMemoryRemoteDeviceRegistry |
Paired-device inventory, status, revoke. |
| Approval service | approval-service.ts:createInMemoryRemoteGatewayApprovalService |
Pending approvals (pending → approved/denied/cancelled/expired), TTL expiry, continuation handler. |
| Audit log | audit-log.ts:createInMemoryRemoteGatewayAuditLog |
Hash-chained entries via computeRemoteAuditEntryHash. |
| Command dispatcher | command-dispatcher.ts:createInMemoryRemoteGatewayCommandDispatcher |
Policy eval → approval → host send → client events. |
| Host connections | host-connections.ts:createRemoteHostConnectionManager |
The /v1/hosts/connect WebSocket server, heartbeats, command.dispatch. |
| Session lifecycle | session-lifecycle.ts |
start/stop/pause/resume/takeover. |
| Timeline | timeline.ts:createRemoteGatewayTimelineService |
Unified audit + artifact + approval + session view. |
| Pairing codes | pairing-codes.ts |
One-time code create/redeem/expire. |
5.2 HTTP surface (selected; full list in code)#
GET /health GET /v1/devices POST /v1/commands
GET /v1/health GET /ready GET /v1/ready GET /v1/devices/{id} GET /v1/commands/{id}
POST /v1/pairing/exchange POST /v1/devices/{id}/revoke POST /v1/commands/{id}/cancel
POST /v1/sessions GET /v1/sessions GET /v1/approvals POST /v1/streams … /stop … /source
GET /v1/sessions/{id} …/end …/takeover POST /v1/approvals/{id}/decisions
POST /v1/artifacts GET /v1/artifacts GET /v1/timeline GET /v1/audit/export
GET /v1/diagnostics
5.3 Host channel (WebSocket)#
Path /v1/hosts/connect (host-connections.ts). Message kinds:
- host → gateway:
host.handshake,command.progress,command.result,command.error. - gateway → host:
host.handshake.accepted,command.dispatch. - liveness: WebSocket ping/pong on
hostHeartbeatIntervalMs(default 30 s), disconnect afterhostHeartbeatTimeoutMs(default 90 s).
5.4 Configuration (config.ts)#
All keys are read by loadRemoteGatewayConfig. The important ones:
| Env var | Default | Purpose |
|---|---|---|
BELLONA_REMOTE_GATEWAY_PORT / PORT |
4070 |
HTTP+WS port. |
BELLONA_REMOTE_GATEWAY_HOST / HOST |
127.0.0.1 |
Bind address. |
BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET |
dev secret (≥32 chars) | HMAC key for host tokens. Must be set in prod. |
BELLONA_REMOTE_GATEWAY_HOST_TOKEN_TTL_MS |
90 days | Host-token validity. |
BELLONA_REMOTE_GATEWAY_PAIRING_CODE_TTL_MS |
600 000 (10 min) | Pairing-code window. |
BELLONA_REMOTE_GATEWAY_APPROVAL_REQUEST_TTL_MS |
60 000 | Approval pending TTL. |
BELLONA_REMOTE_GATEWAY_HOST_HEARTBEAT_INTERVAL_MS / …_TIMEOUT_MS |
30 000 / 90 000 | Heartbeat. |
BELLONA_REMOTE_GATEWAY_STORE_FILE |
(unset) | If set, file-backed persistent store. |
BELLONA_REMOTE_GATEWAY_SHUTDOWN_GRACE_MS |
5 000 | Graceful-shutdown window. |
HTTP routes are currently unauthenticated (host-channel auth is enforced; the operator-facing REST API is bound to loopback / behind the cloud TLS edge rather than carrying its own bearer token). The SDK does attach
Authorization: Bearer <hostToken>/X-API-Keyheaders when configured, so the gateway can adopt route auth without an SDK change.
6. The Host & adapters#
createRemoteHostApp (apps/bellona/remote-host/src/app.ts) wires three pieces:
- Adapter registry —
adapter-registry.ts:createInMemoryRemoteHostAdapterRegistry. By default it registers the fake Blender adapter (blender.scene.query), the real Blender / browser / unreal / file / desktop adapters, plus thehost-diagnosticsandremote-host-stateadapters. - Command executor —
command-executor.ts:createInMemoryRemoteHostCommandExecutor. Runs a policy preflight, then races adapter execution against the command timeout and an abort signal, emittingcommand.accepted/started/progressthencommand.completed/failed/timed-out/cancelled. - Gateway connection —
gateway-connection.ts:createRemoteHostGatewayConnectionManager(WebSocket out toBELLONA_REMOTE_HOST_GATEWAY_URL, defaultws://127.0.0.1:4070/v1/hosts/connect), with exponential-backoff reconnect.
6.1 The adapter contract#
Every adapter is a RemoteHostAdapterRegistration
(adapter-registry.ts): an adapter descriptor, the RemoteCapability[] it
advertises (each capability lists commandNames and the permission scopes it
needs), and a commandHandlers map keyed by full command name. A handler has the
signature:
type RemoteHostAdapterCommandHandler = (
command: RemoteCommandEnvelope,
context?: RemoteHostAdapterCommandContext,
) => RemoteCommandArguments | Promise<RemoteCommandArguments>;
The registry's routeCommand matches the envelope's command name to the
advertising capability and dispatches to the handler. Adding a real DCC operation
is "declare a capability + write a handler", not "edit the executor" — see the
developer guide.
6.2 Host configuration (apps/bellona/remote-host/src/config.ts)#
| Env var | Default | Purpose |
|---|---|---|
BELLONA_REMOTE_HOST_GATEWAY_URL |
ws://127.0.0.1:4070/v1/hosts/connect |
Gateway WS endpoint. |
BELLONA_REMOTE_HOST_HEALTH_PORT / HOST |
4071 |
Host health server. |
BELLONA_REMOTE_HOST_IDENTITY_STORAGE |
macos-keychain |
macos-keychain or development. |
BELLONA_REMOTE_HOST_IDENTITY_FILE |
~/.oshun/bellona/remote-host.identity.dev.json |
Dev identity file. |
BELLONA_REMOTE_HOST_GATEWAY_RECONNECT_* |
1 000 / 10 / 10 000 | Reconnect interval / attempts / max interval. |
7. The Control Room#
apps/bellona/control-room is a React + Vite SPA. It is feature-flagged off by
default — config.ts:CONTROL_ROOM_FEATURE_FLAG =
VITE_BELLONA_CONTROL_ROOM_ENABLED; isControlRoomEnabled(env) gates the
/control-room route. Its workspace views (App.tsx:createWorkspaceViews)
include: Devices, Session, Review, Timeline, Approvals, Stream, Replay, Diff,
Search, Cost, Mosaic, Notes, Bookmarks, Share, Audit.
Key state modules: approval-queue.ts (applyControlRoomApprovalAction),
session-timeline.ts (createControlRoomSessionTimelineState),
operator-controls.ts (the 10 ControlRoomOperatorActionId actions —
pause/resume/stop/takeover/release-takeover/approve-once/approve-for-session/deny/edit-constraints/ask-revise-plan),
replay-view.ts (six replay lanes, frame-accurate seek). The Control Room is a
gateway client; it never holds privileged state of its own. Placement rationale:
adr/ADR-0006-control-room-placement.md.
8. Cloud deployments#
Two reference deployments live under deploy/bellona-remote/. Both run the same
gateway image; only the surrounding infrastructure differs.
8.1 Hetzner (180.C.25.08) — single node, Docker Compose#
deploy/bellona-remote/hetzner/docker-compose.prod.yml. Caddy terminates TLS on
80/443; the gateway (4070) is on a private Docker network only; coturn
provides STUN/TURN (3478/5349 + relay range); Postgres + MinIO + Prometheus +
Grafana + Loki round out the stack; a nightly pg-backup cron dumps + mirrors to
MinIO with SHA-256 checksums. The Hetzner Cloud firewall opens only 80/443 and
the TURN ports — never 4070/5432/9000. Full runbook:
hetzner-reference-deployment.md.
8.2 AWS (180.C.25.09) — Terraform, ALB + Fargate#
deploy/bellona-remote/aws/*.tf. An internet-facing ALB (TLS, 75 s idle timeout,
sticky sessions to pin a host's WSS tunnel) forwards to an ECS Fargate gateway
service on 4070 in private subnets; RDS Postgres (multi-AZ, encrypted) and
ElastiCache Redis (TLS) are reachable only from the gateway SG; a coturn EC2 with
an Elastic IP serves TURN; secrets come from Secrets Manager; CloudWatch alarms +
dashboard cover ALB/ECS/RDS/TURN health. Full runbook:
aws-reference-deployment.md.
Both keep the gateway off the public internet except through the TLS edge, and keep engine/debug ports loopback-bound on the host — the same posture as the LAN setup.
9. Where to go next#
- Set it up / operate it: User & Operator Guide (29.02)
- Extend it: Developer Guide (29.03)
- Run the whole spine locally in 5 minutes: Quickstart (29.13)
- Cross-platform host porting: Host Permission Abstraction (29.16)
- Index of all remote-control docs: README