Step-by-step setup

Quick requirements
  • macOS 12 or newer, Windows 10/11, or Linux with terminal access.
  • Internet access for download and first setup.
  • A Nous Portal account or another supported model provider/API key.
  • Permission to install apps and approve local tool access.

1. Open the official Desktop page

Go here first:

https://hermes-agent.nousresearch.com/desktop

The page currently labels Hermes Desktop as open source under the MIT license and shows platform options for macOS 12+, Windows 10/11, and Linux.

2. Install on macOS

On macOS, use the official .dmg download from the Hermes Desktop page:

https://hermes-assets.nousresearch.com/Hermes-Setup.dmg

Open the .dmg, move Hermes into Applications if prompted, then launch it. If macOS shows a Gatekeeper prompt, confirm that the installer came from the official Hermes source before approving it.

The official installation docs say desktop builds ship signed or notarized macOS artifacts and checksum files, so avoid any macOS installer that does not come from the official page or GitHub release.

3. Install on Windows

On Windows 10 or Windows 11, use the official .exe download:

https://hermes-assets.nousresearch.com/Hermes-Setup.exe

Run the installer, accept normal Windows prompts only after confirming the source, then launch Hermes Desktop from the Start menu.

The official docs describe the Windows desktop installer as a thin GUI installer. On first launch, it can provision the native Hermes setup underneath, including Python through uv, Node, PortableGit, and the dependencies Hermes needs.

4. Install on Linux

The Hermes Desktop page shows Linux support, but the official docs currently separate native Desktop downloads as macOS + Windows and list Linux under the one-line terminal installer.

For Linux, use the official install command from the Hermes docs:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Then reload your shell and start Hermes:

source ~/.bashrc
hermes

If the Desktop page later adds a Linux AppImage, .deb, .rpm, or another native package, use the current official Desktop page or GitHub release instead of old commands.

First-run setup

After Hermes Desktop opens, keep the first setup simple.

  1. Sign in with Nous Portal or configure another supported model provider.
  2. Choose a model or run the guided setup.
  3. Start with a low-risk test workspace.
  4. Review tool permissions before allowing file, shell, browser, or automation access.
  5. Ask Hermes to do one small task before connecting messaging gateways or scheduled jobs.

For the fastest Portal-based setup, the official docs also show:

hermes setup --portal

That path logs Hermes into Nous Portal and configures the bundled model/tool gateway flow. Use it if you are comfortable with the terminal and want the CLI setup path as well.

Verify it works

A basic working install should let you:

  • Open Hermes Desktop.
  • Reach the setup or chat interface.
  • Configure a model provider or Nous Portal account.
  • Start a first conversation.
  • Approve or deny tool actions deliberately.
  • Run hermes doctor from a terminal if the CLI layer was installed.

If Hermes launches but cannot answer, the problem is usually provider setup, account login, API key configuration, or a missing dependency from the underlying agent install.

Desktop app vs CLI vs browser workspace

Use Hermes Desktop when you want the quickest native-app start.

Use the Hermes CLI when you want terminal-first control, scripts, direct setup commands, gateway work, cron jobs, or deeper automation.

Use the Hermes browser workspace when you specifically want the web dashboard or browser-based workspace flow.

The desktop app does not make the advanced paths irrelevant. It gives beginners a friendlier front door.

Common problems

The installer is blocked

Confirm the file came from the official Hermes Desktop page or GitHub release. Do not bypass operating-system warnings for a copied installer link.

Linux users cannot find a desktop package

Use the official terminal installer. The current docs describe Desktop downloads for macOS and Windows, while Linux uses the Hermes Agent terminal path.

Hermes opens but no model works

Run setup again, sign in to Nous Portal, or configure another supported provider. The app still needs a model route.

Tool access feels too broad

Start with a test folder. Do not give an agent broad file or shell access until you understand the approval prompts and what the task requires.

Pricing note

Hermes Agent is open source under the MIT license. Nous Portal is separate and currently shows Free, Plus, Super, and Ultra plans. The Portal page lists paid tiers with monthly credits and access to hosted tool use. Use the current Portal page before choosing a paid plan because plan details can change.

Bottom line

For most beginners, install Hermes Desktop from the official page, use macOS .dmg or Windows .exe, complete provider setup, then run one small task. On Linux, use the official terminal installer for now. Keep the first session narrow, approve tools carefully, and move to the CLI or browser workspace only when you need deeper Hermes features.