Quickstart
Install Harmony, open a workspace, connect a provider, and finish a real first session in about five minutes.
This page takes you from nothing installed to a finished piece of work on your machine. It assumes you already use at least one coding agent CLI (Claude Code, Codex, Cursor, or similar). If you do not, connect a provider covers that first.
Unsure whether you want Core, Cloud, or the website? Start at choose your setup.
Outcome: Harmony installed, a workspace open on a real repository, one agent running in a pane, and one change you reviewed yourself.
Launch path (every unanswered question becomes support)
Work these in order the first time you ship Harmony to a new machine:
| Step | Doc |
|---|---|
| 0. Which surface? | Choose your setup |
| 1. Install for your OS | Installation · Windows · macOS · Linux |
| 2. First workspace | Your first workspace |
| 3. Add and authenticate an agent | Connect a provider · First agent session |
| 4. CLI | CLI reference |
| 5. MCP (agents driving the workspace) | MCP integration |
| 6. Keyboard shortcuts | Desktop shortcuts |
| 7. When something breaks | Troubleshooting |
| 8. Remove cleanly | Uninstall |
| Away from that machine? | Use Harmony in a browser — optional Cloud supervision on this website, not a desktop substitute |
Names you will see
Harmony is the product. The desktop app, the harmony command, and this
website use that name. The terminal surface is the Harmony TUI; it still launches as nala,
and some installer files still start with NALA-, because that is the original
binary name; renaming them would break existing installs. Both talk to the
same local workspace. nala starts the terminal agent; harmony desktop (or
nala desktop) opens the desktop app.
Before you start
| Requirement | Detail |
|---|---|
| Operating system | Windows, macOS, and Linux when download lists a build for your OS |
| Disk | Hundreds of MB for the app (sizes on /download); more if you use voice models |
| Network | Needed for the download and for whichever provider you use. Local Core does not need a Harmony account. |
| A provider | An agent CLI you already have access to |
PREVIEW
Preview builds are free and unsigned. The installers verify size and SHA-256 before running anything. See the unsigned install guide for SmartScreen and Gatekeeper. What is published is exactly what /download shows.
1. Install
Windows (PowerShell):
irm https://ideharmony.com/install.ps1 | iex
macOS / Linux:
curl -fsSL https://ideharmony.com/install.sh | sh
Both scripts ask the site which build is current, verify the download against the published SHA-256 and byte size, then install only if both match. If either check fails the script stops rather than executing the file.
Prefer to read a script before running it? That is the better habit. See installation.
Expected result: the installer completes and nala is available on your
PATH.
Verify:
harmony version
If the command is not found, open a new terminal. PATH changes do not reach shells that were already running.
2. Open a workspace
Launch the desktop app and point it at a real repository:
harmony desktop
A workspace is a named context with its own pane tree, working directory, and status. Create one for the project you actually want to work on rather than exploring in a scratch directory: the interesting behaviour — git status, worktrees, tasks — only appears against a real repo.
Expected result: a window with one terminal pane, and your repository's branch shown in the status bar.
3. Connect a provider
Open the bottom orchestration bar and launch a provider you already have installed. Harmony does not resell model access; it launches the CLI you already pay for, in a pane it manages. Network and token charges belong to that provider, on the machine where the CLI runs.
IMPORTANT
Installed is not the same as authenticated. Harmony can detect that a provider binary exists and still be unable to run a turn because you have not signed in to that provider. If a launch fails, check authentication first.
Verify: the provider's pane reaches its own ready prompt. See connect a provider for per-provider detail.
4. Run one real task — then review it
Do not treat a first run as an automatic multi-provider demo. A workflow that matches what Harmony actually launches:
- Open the repo in Harmony (first workspace).
- Launch Claude Code and ask for a small, bounded change.
- Launch Codex CLI in another pane (or after Claude finishes) and ask it to review the diff — not to overwrite it unattended.
- Read
git diff, run your tests, and approve or reject in the approval UI. Agent-reported success is not evidence.
While a local session is running you can close the desktop window. The daemon keeps the PTY; reopening reattaches. That is not the same as a reboot restoring the exact agent conversation — durable sessions.
Verify:
harmony tasks list
The task you just ran should appear with its state.
5. Try the terminal agent
The same daemon backs a terminal-native agent. From any terminal, in your project directory:
nala
This is the Harmony TUI — the same tasks, artifacts, and messages as the desktop, in a keyboard-only surface. Start work in one and pick it up in the other while the daemon is up.
If something goes wrong
| Symptom | Where to look |
|---|---|
| Install fails, or the hash check stops it | Installation troubleshooting |
nala not found after install | Open a new terminal, then installation troubleshooting |
| Provider launches but never responds | Provider troubleshooting |
| Desktop opens but panes stay blank | Daemon troubleshooting |
The fastest general diagnostic is:
harmony doctor
Next
- Installation — every install method, and how to verify one.
- How Harmony works — the daemon, the surfaces, and what session survival actually means.
- First orchestration run — delegate work to more than one agent (experimental).
- Use Harmony in a browser — Cloud supervision from this website when you are not at that machine.