# Quickstart Source: https://docs.ideharmony.com/getting-started 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](/docs/getting-started/connect-a-provider) covers that first. Unsure whether you want Core, Cloud, or the website? Start at [choose your setup](/docs/getting-started/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](/docs/getting-started/choose-your-setup) | | 1. Install for your OS | [Installation](/docs/getting-started/installation) · [Windows](/docs/getting-started/windows) · [macOS](/docs/getting-started/macos) · [Linux](/docs/getting-started/linux) | | 2. First workspace | [Your first workspace](/docs/getting-started/first-workspace) | | 3. Add and authenticate an agent | [Connect a provider](/docs/getting-started/connect-a-provider) · [First agent session](/docs/getting-started/first-agent-session) | | 4. CLI | [CLI reference](/docs/cli) | | 5. MCP (agents driving the workspace) | [MCP integration](/docs/customization/mcp) | | 6. Keyboard shortcuts | [Desktop shortcuts](/docs/desktop/keyboard-shortcuts) | | 7. When something breaks | [Troubleshooting](/docs/troubleshooting) | | 8. Remove cleanly | [Uninstall](/docs/getting-started/uninstall) | | Away from that machine? | [Use Harmony in a browser](/docs/getting-started/web-app) — 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 `harmony desktop`) opens the desktop app. ## Before you start | Requirement | Detail | |---|---| | Operating system | Windows, macOS, and Linux when [download](/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](/download#first-open) > for SmartScreen and Gatekeeper. What is published is exactly what /download shows. ## 1. Install **Windows (PowerShell):** ```powershell irm https://ideharmony.com/install.ps1 | iex ``` **macOS / Linux:** ```bash 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](/docs/getting-started/installation). **Expected result:** the installer completes and `nala` is available on your `PATH`. **Verify:** ```bash 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: ```powershell 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](/docs/getting-started/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: 1. Open the repo in Harmony ([first workspace](/docs/getting-started/first-workspace)). 2. Launch **Claude Code** and ask for a small, bounded change. 3. Launch **Codex CLI** in another pane (or after Claude finishes) and ask it to review the diff — not to overwrite it unattended. 4. 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](/docs/concepts/session-survival). **Verify:** ```powershell 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: ```powershell nala ``` This is the [Harmony TUI](/docs/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](/docs/troubleshooting/installation) | | `nala` not found after install | Open a new terminal, then [installation troubleshooting](/docs/troubleshooting/installation) | | Provider launches but never responds | [Provider troubleshooting](/docs/troubleshooting/providers) | | Desktop opens but panes stay blank | [Daemon troubleshooting](/docs/troubleshooting/daemon) | The fastest general diagnostic is: ```powershell harmony doctor ``` ## Next - [Installation](/docs/getting-started/installation) — every install method, and how to verify one. - [How Harmony works](/docs/concepts/architecture) — the daemon, the surfaces, and what session survival actually means. - [First orchestration run](/docs/getting-started/first-orchestration-run) — delegate work to more than one agent (experimental). - [Use Harmony in a browser](/docs/getting-started/web-app) — Cloud supervision from this website when you are not at that machine.