Eve library

Bellona Remote Creative Control Plane — Architecture (180.C.29.01)

Guide

Revision 1

On this page

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.

text
            ┌────────────────────────────────────────────────────────────┐
            │  @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 by RemoteActorChainSchema (libs/bellona/remote-protocol/src/actor.ts). This is what the audit log and watermark bind a command to.
  • riskClass — one of read-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 destructive or privileged command must set approvalRequired=true.
  • A safe-mutation / destructive / privileged command must declare a metadata.rollbackStrategy (one of RemoteRollbackStrategySchema: undo_stack | snapshot_restore | compensating_action | manual_remediation_only).
  • A destructive / privileged command 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).
  • timeoutMs may not exceed the maximum for its timeoutClass.
  • target.commandName must start with target.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#

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

text
 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 in apps/bellona/remote-host/src/gateway-connection.ts:sendHandshake.
  • Device keys & clone detection. device-key.ts models 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:evaluateGatewayPin pins the gateway's leaf-cert fingerprint at first trust and refuses a changed key (possible MITM) unless an authorized re-pin rotates it. Backed by FileRemoteHostGatewayPinStore (atomic temp-then-rename writes).
  • Discovery is not trust. mDNS discovery (transport.ts, service _bellona-host._tcp) only finds an endpoint; a candidate is unverified until 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. a delete verb adds command.execute.destructive; a desktop observe verb adds desktop.observe; a browser real-profile request adds browser.profile.real) and resolves them against the device's granted permissions, returning allowed | requires-approval | denied with 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:enforceHostLocalDeny runs after gateway authorization and can only deny — by namespace, command name/prefix, risk class, target device, argument path/origin, or the sensitive-path guard. applyHostLocalDenyAfterAuthorization composes them with AND logic: a gateway "yes" can be downgraded to "no", never the reverse.
  • Sensitive-path default-deny. sensitive-paths.ts:isSensitiveProtectedPath is 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 / redactRemoteSurface deterministically 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 / verifyStreamWatermark applies 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 / verifyAuditChain is the single authoritative tamper-evident chain (each entry hashes its content + the previous hash). assertHighTrustCommandChained fail-loud-refuses to leave a high-trust command unchained.
  • Right to erasure. erasure.ts reconciles 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:resolveIncidentalSubjectDisposition is 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-only hard-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: RemoteTunnelDedupeEntrySchema keys 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)#

text
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 after hostHeartbeatTimeoutMs (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-Key headers 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:

  1. 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 the host-diagnostics and remote-host-state adapters.
  2. Command executor — command-executor.ts:createInMemoryRemoteHostCommandExecutor. Runs a policy preflight, then races adapter execution against the command timeout and an abort signal, emitting command.accepted/started/progress then command.completed/failed/timed-out/cancelled.
  3. Gateway connection — gateway-connection.ts:createRemoteHostGatewayConnectionManager (WebSocket out to BELLONA_REMOTE_HOST_GATEWAY_URL, default ws://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:

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