# Harmonia

Harmonia is a distributed evolutionary homoiconic self-improving agent built on SBCL Common Lisp with Rust capability libraries connected via explicit FFI boundaries. It plans, executes, remembers, secures, and evolves under policy gates with rollback and accounting built in.

## Public Product Map

The clean public model is a 2x2 matrix:

| Interface | Agent | App |
|-----------|-------|-----|
| **CLI** | **CLI Agent** — terminal-first self-managed runtime on macOS, Linux, Windows, and FreeBSD | **CLI App** — the TUI remote client installed from the same `harmonia` product with `--tui-only` |
| **GUI** | **GUI Agent** — desktop graphical agent on macOS, Linux, Windows, and FreeBSD | **GUI Apps** — iOS, watchOS, tvOS, Android, Web, OpenXR, and desktop GUI remote mode |

Two rules keep the model simple:

- **Agents run Harmonia**
- **Apps connect to agents**

Managed cloud is not a separate product class. It is a **deployment mode of an agent**.

## Deployment Modes

- **CLI Agent** — self-managed, terminal-first, full runtime
- **GUI Agent** — self-managed, desktop graphical runtime
- **Managed Agent** — cloud-operated deployment managed by Harmoniis

All three pair with the same CLI and GUI app family.

## Install

### CLI Agent

**macOS / Linux / FreeBSD**

```bash
curl --proto '=https' --tlsv1.2 -sSf https://harmoniis.com/harmonia/install | sh
```

**Windows**

```powershell
iwr https://harmoniis.com/harmonia/install.ps1 -UseB | iex
```

**From source**

```bash
cargo install harmonia && harmonia setup
```

### CLI App

The CLI App is the TUI remote client. It comes from the same `harmonia` product and installs with the lightweight remote-client mode.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://harmoniis.com/harmonia/install | sh -s -- --tui-only
```

This installs the TUI remote client, local wallet identity, and pairing path without installing the full agent runtime.

### GUI Apps and GUI Agent

The GUI family covers:

- **GUI Apps** on iOS, watchOS, tvOS, Android, Web, OpenXR, and desktop GUI remote mode
- **GUI Agent** on macOS, Linux, Windows, and FreeBSD

GUI Apps are remote clients, not passive chat shells. They can expose local files, notifications, device context, and other policy-scoped resources to the agent.

## Quick Start

For a self-managed CLI Agent:

```bash
harmonia setup
harmonia start
```

The setup flow configures the wallet path, model provider, and enabled frontends.

Then pair the surfaces you want:

- **CLI App / desktop GUI remote mode** over Tailscale
- **iOS, watchOS, tvOS, Android, OpenXR** over MQTT mTLS
- **Web GUI App** over HTTP/2 mTLS

## Runtime Shape

Harmonia keeps product roles separate from gateway frontends:

- **Product roles** are CLI Agent, GUI Agent, CLI App, and GUI Apps
- **Gateway frontends** are runtime communication modules loaded into the agent

The current agent exposes **13 frontends** through the gateway/baseband architecture: TUI, MQTT, HTTP/2, Telegram, Slack, Discord, Signal, WhatsApp, iMessage, Mattermost, Nostr, Email, and Tailscale.

## Supported Platforms

| Family | Platforms |
|--------|-----------|
| **CLI Agent / CLI App** | macOS, Linux, Windows, FreeBSD |
| **GUI Agent** | macOS, Linux, Windows, FreeBSD |
| **GUI Apps** | iOS, watchOS, tvOS, Android, Web, OpenXR, desktop GUI |

## Next Steps

- [Architecture](/docs/harmonia/architecture) — 6-layer model, 9 FFI ports, tick model, and configuration
- [Self-Improvement](/docs/harmonia/self-improvement) — Ouroboros, Phoenix, and the three-layer evolution model
- [Harmonia vs OpenClaw](/docs/harmonia/vs-openclaw) — framework comparison
- [Frontends](/docs/harmonia/frontends) — gateway frontends, app transports, and channel architecture