# 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**:

| Frontend | Runtime Module | Transport | Notes |
|----------|----------------|-----------|-------|
| **TUI** | `tui` | Terminal | Always-on local terminal surface for the agent runtime |
| **MQTT** | `mqtt-client` | MQTT 5.0 mTLS | Mobile, XR, and device-oriented remote GUI transport |
| **HTTP/2** | `http2-mtls` | HTTP/2 mTLS | Web GUI transport with authenticated streaming |
| **Telegram** | `telegram` | Bot API | |
| **Slack** | `slack` | Bot API | |
| **Discord** | `discord` | Bot API | |
| **Signal** | `signal` | signal-cli bridge | |
| **WhatsApp** | `whatsapp` | Cloud / bridge API | |
| **iMessage** | `imessage` | BlueBubbles | macOS only |
| **Mattermost** | `mattermost` | Bot API | |
| **Nostr** | `nostr` | NIP-01 relay | |
| **Email** | `email-client` | IMAP / SMTP | Inbound polling and outbound SMTP |
| **Tailscale** | `tailscale-frontend` | Mesh transport | Remote node and CLI App pairing path |

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

```text
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:

```lisp
(: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](/docs/harmonia/overview) — install, product map, and quick start
- [Architecture](/docs/harmonia/architecture) — 9-port boundary, tick model, and crate inventory
- [Self-Improvement](/docs/harmonia/self-improvement) — evolution and safety gates