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. 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.
Outcome: Harmony installed, a workspace open on a real repository, one agent running in a pane, and one durable task completed.
Launch path (every unanswered question becomes support)
Work these in order the first time you ship Harmony to a new machine:
| Step | Doc |
|---|---|
| 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 |
Before you start
| Requirement | Detail |
|---|---|
| Operating system | Whatever download lists for your channel (Windows, and macOS/Linux when published) |
| 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 |
| 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:
nala 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:
nala 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.
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
Ask the agent for something small and concrete against your repository — a focused refactor, a test for an existing function, a bug you already understand. Small and concrete is the point: you are verifying the loop, not evaluating the model.
While it runs, you can close the desktop window. The daemon keeps the session, scrollback, and conversation alive; reopening reattaches you.
Verify:
nala 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 NALA TUI Agent — 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; nothing is lost either way.
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:
nala doctor
Next
- Installation — every install method, and how to verify one.
- How Harmony works — the daemon, the surfaces, and why sessions survive.
- First orchestration run — delegate work to more than one agent.