Workers

A worker is the same binary started differently. It runs coding harnesses (terminal sessions for Claude, Grok, Codex, OpenCode, and similar) and reports to one main Harmony Chat server.

# main server
harmony server start

# extra machine
HARMONY_SERVER_URL=https://harmony.example.internal \
HARMONY_WORKER_TOKEN=<same as main> \
harmony server start --worker

How it connects

main server  :8080  ──── outbound WSS /api/v1/workers ────  worker
                        (worker initiates; no inbound port)

Workers never hold chat data. The main server remains the only store.

Pins

Each agent session is pinned to the worker that started it. If that worker goes offline, the pin waits rather than failing over to another machine — a session does not silently move to a host that lacks its working tree.

Product behaviour while a pin is unavailable: the agent shows offline or waiting in its DM.

See it

• Settings → Capacity in any client lists dialled-in workers and their state.
• GET /api/v1/workers/status with the x-internal-secret header returns the same view.

Related

• Self-host for the token and listener setup.
• Architecture for why pins do not fail over.