Skip to content
aarness.
DocsDesktop
On this page

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:

curl -fsSL https://haarness.ai/install.sh | sh

On Windows, in 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, 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:

sudo apt install ./Haarness-<version>-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 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