Frontends

Harmonia product roles and Harmonia gateway frontends are not the same thing.

• Product roles are the public surfaces: CLI Agent, GUI Agent, CLI App, and GUI Apps
• Gateway frontends are the runtime channels loaded into the agent through the baseband/gateway architecture

This distinction matters because the same agent can serve many product surfaces through multiple frontends in parallel.

Product Roles vs Runtime Frontends

The public product map is simple:

• Agents run Harmonia
• Apps connect to agents

The transport depends on the app surface:

• CLI App and desktop GUI remote mode pair over Tailscale
• iOS, watchOS, tvOS, Android, OpenXR GUI Apps pair over MQTT mTLS
• Web GUI App pairs over HTTP/2 mTLS

Those transports are implemented as gateway frontends inside the agent.

Supported Frontends

Harmonia currently exposes 13 gateway frontends:

Gateway / Baseband Flow

Every frontend connects through the Baseband port (ports/baseband.lisp to lib/core/gateway and frontend crates). A tick-level flow looks like this:

gateway-poll
  -> enabled frontends emit inbound envelopes
  -> gateway attaches security labels, metadata, taint, and routing context
  -> orchestrator processes signals
gateway-flush
  -> responses route back to the correct frontend/session/channel

For sessionful transports such as MQTT, HTTP/2, and Tailscale, the gateway preserves transport metadata and session identifiers so multiple remote clients can operate in parallel.

Metadata and Signal Shape

Every inbound message becomes a structured signal carrying:

• originating frontend
• sub-channel or route key
• security label
• payload
• capabilities
• metadata
• timestamp
• taint
• dissonance score
• origin fingerprint

The gateway uses that metadata to enforce sender policy, payment/auth policy, and privileged-operation rules before the orchestrator acts.

A2UI and Rendering

A2UI is capability-driven, not frontend-name driven.

• GUI Apps render the richest A2UI surfaces where their transport supports them
• CLI App and text channels receive the same underlying agent output with text-precise fallback
• Agents do not hardcode per-surface response trees; capabilities and metadata determine rendering

This is why the same agent can serve a browser GUI, mobile GUI, desktop GUI, terminal UI, and chat channels without changing the core reasoning model.

Configuration Shape

The runtime frontend inventory lives in config/baseband.sexp. Each entry declares:

• frontend name
• dynamic library path
• security label
• auto-load behavior
• required vault keys and config-store keys

For example, the current baseband config includes both MQTT and HTTP/2 transport frontends:

(:frontends
  ((:name "mqtt"
    :so-path "target/release/libharmonia_mqtt_client.so"
    :security-label :authenticated
    :auto-load :if-vault-keys
    :vault-keys (:mqtt-broker-url :mqtt-cert))
   (:name "http2"
    :so-path "target/release/libharmonia_http2_mtls.so"
    :security-label :authenticated
    :auto-load :if-ready
    :config-keys (("http2-frontend" "bind")
                  ("http2-frontend" "ca-cert")
                  ("http2-frontend" "server-cert")
                  ("http2-frontend" "server-key")
                  ("http2-frontend" "trusted-client-fingerprints-json")))))

Pairing and Remote Roles

Remote pairing is expressed through the product model, not by inventing extra public categories:

• CLI App is the TUI remote client from the CLI product
• GUI Apps are mobile, browser, XR, and desktop GUI remote clients
• Agents are the runtimes those apps pair to

Desktop GUI is special only in one way: the same desktop GUI family can operate as either a GUI App or a GUI Agent.

Next Steps

• Overview — install, product map, and quick start
• Architecture — 9-port boundary, tick model, and crate inventory
• Self-Improvement — evolution and safety gates