> ## Documentation index > Fetch the complete documentation index at: https://haarness.ai/llms.txt > Use this file to discover all available pages before exploring further. # Install and first run Haarness Desktop puts the agent, your project's files, a diff review, terminals and a browser in one window. It includes its own copy of Haarness, so you do not need to install the CLI first. **You will:** install Desktop, open a project and connect a model. **Next:** your first chat in Desktop. ## Install Desktop The Haarness install command installs Desktop after the CLI. On macOS or Linux: ```sh curl -fsSL https://haarness.ai/install.sh | sh ``` On Windows, in PowerShell: ```powershell irm https://haarness.ai/install.ps1 | iex ``` With the CLI already installed, `haarness desktop` opens Desktop and installs it first if it is missing. To install Desktop alone, set `HAARNESS_PRODUCT=desktop` (on Windows, `$env:HAARNESS_PRODUCT='desktop';` before `irm`). The script shows each download's progress and checks its SHA-256 checksum before it installs anything. | Platform | What you get | | --- | --- | | macOS | `/Applications/Haarness.app` (`~/Applications` if you cannot write to `/Applications`) | | Linux | `~/.local/bin/Haarness.AppImage`, a `haarness-desktop` command beside it, and Haarness in your applications menu (with a graphical session) | | Windows | The installer opens and asks where to install | You can also download a build from the [download page](https://haarness.ai/download), which lists every file with its checksum. On macOS the install command clears the download quarantine on the app it has just verified (and gives it a local signature if its own does not check out), so macOS does not stop it at first launch. It changes no system security setting. ### Updates Desktop keeps itself up to date. It checks for a new version shortly after it starts and every half hour after that, and downloads it in the background. When the new version is ready, **Restart to update** appears at the bottom of the sidebar: click it and Haarness restarts on the new version. On macOS and Linux, running chats and terminals keep going while it restarts. Windows cannot replace a program that is running, so there Haarness first stops its background work cleanly: your chats and their history stay, and a reply that was still being written stops. If you just quit instead, macOS and Linux install the update then; on Windows the installer runs only when you click **Restart to update**. Every download is checked against the release's checksum before anything is installed, and on macOS the new app must be signed by Haarness. If something goes wrong (no connection, not enough disk space, a damaged download), nothing changes: Haarness tries again later and **Settings → About** says why. You can also check right away there, or with **Check for updates…** in the app menu (the Help menu on Windows and Linux). To be asked before anything downloads, turn off **Download updates automatically** in **Settings → About**. Haarness still tells you when a new version is out: **Update to <version>** appears in the sidebar, and clicking it downloads the update and shows its progress there. A copy run straight from its disk image on macOS asks you to **Move to Applications** first. If Haarness cannot replace itself (it is installed where your account cannot write, or from the Linux `.deb`), **Download installer** saves the new installer in your Downloads folder and opens it. Versions before 0.1.6 do not update themselves: install 0.1.6 or later once with the install command above. ### Linux: FUSE and the .deb package On Linux, the menu entry also opens `haarness://` links. An AppImage normally needs FUSE 2, which Ubuntu has not installed by default since 22.04; without it, `haarness-desktop` has the AppImage unpack itself each time it starts, which is slower. Install `libfuse2` (`libfuse2t64` on Ubuntu 24.04 and later) to start it directly. On Debian and Ubuntu you can instead install the `.deb` from the [download page](https://haarness.ai/download): ```sh sudo apt install ./Haarness--linux-x64.deb ``` It adds the same `haarness-desktop` command and menu entry system-wide, and needs no FUSE. ## Open a project 1. Launch Haarness. The first screen says **Open a project to get started**. 2. Click **Open project** and choose your project folder. 3. A new chat asks **What should we work on in <project>?** Each project keeps its own chats. To add another project later, use **File → Open project…** (⌘O on macOS, Ctrl+O elsewhere) or the **+** button beside **Projects** in the sidebar. ## Connect a model If nothing can answer yet, Desktop opens **Welcome to Haarness** as soon as the project is open. Pick one way in: | Choice | What it does | | --- | --- | | **Use Haarness Cloud** | Cloud models on your Haarness plan. No API keys | | A provider under **Popular** or **More providers** | Sign in with a subscription such as ChatGPT, or paste the provider's API key | | **Custom endpoint**, under **Something else** | Any OpenAI-, Anthropic- or Gemini-compatible API | | **Haarness Router**, under **Something else** | A router you host yourself | Type in **Search providers…** to find one quickly. A check mark shows the providers that are already connected. Ollama and LM Studio need no setup: if one is running on this computer, its models are already in the model picker. When it is the only thing connected, an empty chat says once where replies come from, with a link to connect a provider. ### Sign in with a subscription 1. Choose the provider, for example **OpenAI** to use your ChatGPT plan. If it offers more than one way, pick one under **How do you want to connect?**, such as **Sign in with ChatGPT**. 2. Your browser opens the sign-in page. If the provider uses a code, Desktop shows it under **Enter this code when asked:** with a **Copy code** button. 3. Finish in the browser. Desktop shows **Waiting for you to finish in the browser…** and closes the dialog when you are done. If the browser sign-in does not come back, choose **Use a code instead**. ### Paste an API key 1. Choose the provider. **Create a key** opens the provider's page where you make one. 2. Paste the key into **Paste it here** and click **Connect**. Haarness checks the key with the provider first; if the provider refuses it, the dialog says why and saves nothing. The key is **Saved on this computer, never in your project**, in a file only your user can read. When Desktop is connected to a remote server, the key is saved on that server instead. **Other ways to connect** names the environment variable you can set instead. ### It worked when A notice says **<provider> is connected**, and the model button in the message box shows a model name instead of **Connect a provider**. You can change providers at any time in **Settings → Providers**. ## Sign in to Haarness Cloud Choose **Use Haarness Cloud** in the connect dialog, or **Sign in to Haarness** at the bottom of the sidebar. In the panel that opens, click **Sign in to Haarness** and finish in your browser. Back in Desktop, Haarness Cloud models appear in the model picker, and the account panel shows your plan, credits and Cloud workspaces. You do not need an account to use Desktop with your own keys. See [Local or Cloud](https://haarness.ai/docs/start/local-or-cloud.md) for what an account adds. ## Close the window without stopping work Closing Desktop does not cancel a running turn. Desktop and the terminal UI share the same Haarness server for each project folder, so running `haarness` in that folder and opening `/sessions` shows the same chats. ## Next - [Work in a chat](https://haarness.ai/docs/desktop/the-conversation.md): ask, approve, stop and undo - [Connect a provider](https://haarness.ai/docs/start/connect-a-provider.md): every way to get a model, including the CLI