Harmony Releases

Public release repository for Harmony Configuration Distribution System.

About

This repository contains binary releases for:

• HarmonyClient — Cross-platform sync client for deploying software configurations
• HarmonyInstaller — Interactive installer for setting up Harmony servers

Source code is in a separate private repository.

Downloads

Latest Releases

Visit the Releases page to download:

• HarmonyClient.zip — Cross-platform client application

  • Tagged as: harmony-v* (e.g., harmony-v0.1.23)
  • Self-contained executable with all dependencies

• HarmonyInstaller — Server installation tool

  • Tagged as: installer-v* (e.g., installer-v1.1.14)
  • Available for Windows (HarmonyInstaller-win-x64.zip) and Linux (HarmonyInstaller-linux-x64.tar.gz)
  • Self-contained executable with all dependencies

Direct Download Links

• Client: HarmonyClient.zip
• Installer (Windows): HarmonyInstaller-win-x64.zip
• Installer (Linux): HarmonyInstaller-linux-x64.tar.gz

Quick Start

1. Install the Server

1. Download the installer for your platform
2. Extract and run it:
   • Windows: HarmonyInstaller.exe
   • Linux: ./HarmonyInstaller
3. Follow the interactive wizard — it handles Docker, SSL, database, and your admin account

The installer creates:

• harmony_nginx — Reverse proxy with SSL (HTTP→HTTPS redirect)
• harmony_server — Harmony web server
• harmony_martenhost — PostgreSQL (event sourcing)
• harmony_identity — PostgreSQL (authentication)
• harmony_log_server — Seq centralized logging
• harmony_certbot — (Let's Encrypt only) automatic SSL renewal

2. Install Clients

Download HarmonyClient.zip from this releases page and run it on user machines.

On first run, the client:

1. Requests a device code from the server
2. Opens a browser for the user to log in and approve the device
3. Receives authentication tokens via SSE — no passwords stored on client machines
4. Begins syncing assigned configuration files automatically

On Windows, the client offers to install itself as a Windows Service. For enterprise rollouts, use --install-service for unattended installation via SCCM, Group Policy, or your deployment tool of choice.

Client Configuration

Environment Variables

Variable	Purpose	Required
HARMONY_SERVER_URL	Server base URL (use https://)	Yes
HARMONY_USER_EMAIL	User email for authentication	Yes

Variable	Purpose	Default
HARMONY_ALLOW_SELF_SIGNED_CERT	Accept self-signed TLS certs	false
HARMONY_USER_ID	User GUID	Auto-assigned on enrollment
HARMONY_ORG_ID	Organization GUID	Auto-assigned on enrollment
LOG_SERVER_URL	Seq endpoint for CLEF log ingestion	Disabled
OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry collector	Disabled

Device ID is derived automatically from a platform-specific hardware identifier (not configurable):

Platform	Source
Windows	HKLM\...\MachineGuid
Linux	/etc/machine-id
macOS	IOPlatformUUID via ioreg

Authentication

The client uses Device Authorization Flow — an OAuth-style device code grant:

1. Client contacts the server and receives a device code + approval URL
2. User's browser opens to the approval page
3. User logs in (if needed) and approves the device
4. Client receives JWT + refresh token via Server-Sent Events
5. Refresh tokens rotate automatically; reuse detection revokes compromised token families

No passwords are ever stored on client machines.

Logging

The client logs to four backends simultaneously:

• Console — emoji-prefixed human-readable output
• File (CLEF) — JSON lines at {install dir}/harmony-client.log, 10MB rotation
• ILogger/OTEL — structured properties forwarded to OpenTelemetry
• Log Server (HTTP) — posts CLEF events to {LOG_SERVER_URL}/api/events/raw when configured

Running Seq on client machines for searchable logs

By default, client logs go to console and the local CLEF file. For a searchable log viewer, run a local Seq instance (free for single-user):

Docker:

docker run -d --name harmony-seq --restart unless-stopped -p 5341:80 -v seq-data:/data datalust/seq:latest -e ACCEPT_EULA=Y

Then set:

[Environment]::SetEnvironmentVariable("LOG_SERVER_URL", "http://localhost:5341", "Machine")

Central Seq instance (recommended for IT teams):

Run one Seq instance on your network and point all clients at it — single dashboard with logs from every client, filterable by device ID, user, and organization.

Windows Service

The client runs as a console app or Windows Service from the same binary. On first run, it detects if it's already installed and offers to install or upgrade automatically.

Flag	Effect
--install-service	Install and start as Windows Service (requires elevation)
--upgrade-service	Stop, replace binary, restart (requires elevation)
--start-service	Start the existing service (requires elevation)

These flags exist for enterprise deployment scripts (MSI, SCCM, Group Policy) where interactive prompts aren't appropriate. On non-Windows platforms, the client runs in console mode.

Service startup options

When installing via sc.exe or the built-in installer, the service uses delayed-auto start by default:

Start type	Behavior
delayed-auto	Starts ~2 min after boot (recommended — lets networking finish first)
auto	Starts immediately at boot
demand	Manual start only

Environment variables for the service are read from the machine environment (System Properties → Environment Variables, Group Policy, or registry).

System Requirements

HarmonyInstaller

• Docker and Docker Compose
• Linux or Windows (x64)
• Ports 80, 443 available (or custom ports)

HarmonyClient

• Windows, Linux, or macOS (x64)
• Network access to the Harmony server

Both are self-contained — no separate .NET runtime installation needed.

Troubleshooting

Client can't connect to server

• Verify HARMONY_SERVER_URL is correct and reachable: curl -k https://your-server
• For self-signed SSL: set HARMONY_ALLOW_SELF_SIGNED_CERT=true
• Check firewall rules — ports 80/443 must be open

Device authorization fails

• The user has 15 minutes to approve a device code before it expires
• Ensure the server URL in the client matches the URL in the browser (no trailing slash mismatch)
• Check that the server is running: docker compose ps on the server machine

Config files not syncing

• Verify the user has software packages assigned in the Harmony dashboard
• Verify those packages have config files uploaded
• Check harmony-client.log for sync errors

Installer fails

• Docker must be installed and running before starting the installer
• For Let's Encrypt SSL: your domain's DNS must already point to the server, and port 80 must be open from the internet

License

Proprietary software. All rights reserved.

Support

For issues, questions, or feature requests, contact the maintainer.