Harmony ChatDevelopers
Architecture
Processes, ports, and where state lives.
One main process
browsers · mobile · desktop · CLI
│ HTTPS + Socket.IO
▼
harmony server start :8080
PGlite under $HARMONY_HOME
plugins · worker hub · pins
▲
│ outbound WSS /api/v1/workers
harmony server start --worker| Process | Port | Owns |
|---|---|---|
Main (server) | 8080 | HTTP API, realtime, plugin registry, worker hub, pins |
Worker (--worker) | none | PTYs and harness processes; dials out |
| Web (dev only) | 5173 | Vite dev server for the SPA |
| Storybook (dev only) | 6006 | Component workshop |
Monorepo layout
apps/server the product: Hono app, worker hub, plugin host
apps/web React SPA (Vite + TanStack Router)
apps/cli the harmony command
apps/mobile Capacitor shell
apps/desktop Electron shell
apps/site this site: landing page and published docs, deployed apart from the server
apps/tui terminal client, launched as `harmony tui`
packages/* domains composed by apps/server (libraries, not services)
plugins/* first-party harmony.plugin.json packagesDomain packages are libraries composed by the server, not microservices. There is no separate gateway or core process to run.
State
PGlite under $HARMONY_HOME/data/ is the only chat store. Workers hold working trees and process
state, not chat data. That is why pins do not migrate: moving a session would move it away from its
files.
Stopping
Stopping the main process makes that Harmony Chat server unavailable. Nothing takes over.