Install Harness

Before you begin#

The downloadable app requires an Apple silicon Mac running macOS 15 or later. The graphical app is macOS-only; the daemon and CLI can also be built for a headless Mac or Linux host.

Install the Mac app#

1. Use Download for macOS in the navigation to get the latest published Harness.dmg.
2. Open the disk image and drag Harness.app into Applications.
3. Launch Harness from Applications and follow the first-run tour.

For a checksum check, compare the SHA-256 below with the digest for Harness.dmg on that exact GitHub release—not a checksum from a different version.

shasum -a 256 "$HOME/Downloads/Harness.dmg"

Do not disable Gatekeeper or remove quarantine attributes to bypass an unexpected security warning. Redownload the official release and check its version and checksum first.

Complete the first-run tour#

The tour covers the workspace overview, notifications, and optional command-line installation. Reopen it later from Help → Welcome to Harness. New installations begin in Persistent Terminal mode.

The notification step requests macOS notification permission and offers hooks for detected agents. The command-line step installs harness-cli and HarnessDaemon, adds PATH blocks with backups to the shells you use, and adds fish completions when appropriate. An already-working daemon is not replaced with a new LaunchAgent registration.

Install the CLI manually#

Skip this when the first-run tour already installed the command line. Otherwise run the bundled installer:

/Applications/Harness.app/Contents/MacOS/harness-cli install

Follow the installer output. The standard Mac bin directory can be added to your current zsh or bash session with:

export PATH="$HOME/Library/Application Support/Harness/bin:$PATH"
harness-cli ping

For future shells, add the PATH setting to the appropriate shell profile, or use the tour to configure the shells automatically. The export syntax above is for zsh/bash, not fish.

Check the installation#

Open the app, then use these read-only commands to confirm the CLI can reach the daemon and see the workspace:

harness-cli ping
harness-cli ls
harness-cli daemon-stats --json

A missing command generally means PATH setup is incomplete. An unreachable daemon is a different problem; use the troubleshooting guide rather than reinstalling or deleting your sessions.

Update to 2.0#

Harness 2.0 is available through the built-in update check or the latest published signed Mac download. The website download always follows the newest stable Harness.dmg; review its release notes when updating.

Existing settings and saved sessions remain compatible. Update remote daemons and CLIs separately when using new workspace methods. If a daemon restart is needed, first save work in running programs: persistent sessions are not a checkpoint of process memory.