Hermes Agent Desktop App: Installation & First Use Guide
Beginner10 min read
Hermes Agent Desktop App: Installation & First Use Guide

Hermes Agent Desktop App: Installation & First Use Guide

CATAITO Team2026-08-07
Your operating system:

Learning Objectives

By the end of this tutorial, you will be able to:

  • Download and install the Hermes Agent Desktop app on your operating system
  • Sign in and set up your first chat session
  • Navigate the desktop app interface
  • Use key features: chat, repository discovery, skills, and settings
  • Troubleshoot common issues

Time needed: 10–15 minutes

Difficulty: Beginner

Which version is covered? This tutorial covers the Hermes Agent Desktop app — the native graphical application for macOS, Windows, and Linux. It uses the same agent core, config, sessions, skills, and memory as the Hermes Agent CLI. If you want to work in the terminal instead, see the Hermes Agent CLI Beginner's Guide.

Before You Start

RequirementDetails
Operating systemmacOS, Windows 10/11, or Linux
AccountA Nous Portal account, or an API key from a supported provider
Hermes Agent CLIThe desktop app shares the same agent core — install it via the CLI or the desktop installer
InternetA stable internet connection
What is Hermes Agent Desktop?
Hermes Agent Desktop is a native desktop application built around the same Hermes Agent that runs in the CLI and the messaging gateway. It is not a separate product — everything you set up in the CLI (config, API keys, sessions, skills, memory) is available in the desktop app, and anything you do in the desktop app shows up in the CLI. It runs on macOS, Windows, and Linux.

Download & Install

Hermes Agent Desktop is available for macOS, Windows, and Linux. There are two ways to install it.

Option A: Desktop Installer (Recommended)

Download the installer from the official Hermes Agent website and run it. This installs both the desktop app and the CLI.

  • Windows: click Download for Windows, open the installer, and follow the on-screen instructions. Launch Hermes Agent from the Start menu.
  • macOS: click Download for macOS, open the .dmg file, drag Hermes Agent to your Applications folder, then launch it.
  • Linux: download the AppImage, make it executable (chmod +x), and run it. Alternatively, use Option B below.

Option B: CLI Install + Desktop Command

If you already have the Hermes Agent CLI installed, simply run:

bash
hermes desktop

This launches the desktop app using your existing config, API keys, sessions, and skills. No separate installation needed.

Verify the Installation

When the desktop app opens, you should see the Hermes Agent chat interface with a left sidebar. If you are prompted to sign in, follow the steps below.

First Launch & Setup

Step 1: Sign In

When you first open the desktop app, you may need to sign in to your provider:

  1. 1If you already set up a provider in the CLI, the desktop app uses the same config automatically.
  2. 2If not, click Settings in the left sidebar, then navigate to the Provider section.
  3. 3Click Set up provider and follow the prompts. The fastest path is Nous Portal — a single OAuth login covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser).

Step 2: Explore the Interface

The desktop app is organized as a chat-first window with a left sidebar:

  • Chat — the center of the app. Type messages, receive streaming responses, and see live tool activity as the agent works.
  • Left sidebar — navigate between sessions, projects, skills, MCP servers, plugins, and settings.
  • Status bar (bottom) — shows the YOLO toggle, a context-usage meter, and customizable items. Right-click to customize what appears.
  • Preview rail (right side) — render web pages, files, and tool outputs side by side while you keep chatting.

You can also press Cmd/Ctrl + K to open the command palette for quick access to any feature.

Step 3: Start Your First Chat

  1. 1Make sure a session is selected in the left sidebar.
  2. 2Type a message in the composer at the bottom and press Enter:
text
Hello! What can you do?
  1. 1Hermes Agent responds with a summary of its capabilities, with streaming output and tool activity shown in real time.
  2. 2Try dragging a file into the chat area to attach it to your next message.

Step 4: Try Key Features

  • New session: click the + button next to Sessions in the sidebar to start a parallel conversation.
  • Repository discovery: the desktop app scans your home directory for Git repositories and lists them in the Projects sidebar for quick access.
  • Skills: browse and install skills from the Skills sidebar.
  • MCP servers: configure MCP servers from the MCP sidebar.
  • Plugins: install desktop UI plugins to add custom panes and commands.
  • Themes: customize the app's appearance with skins and themes.

Troubleshooting

IssueSolution
Desktop app does not openMake sure your system meets the requirements. On Linux, ensure the AppImage is executable (chmod +x).
"No provider configured"Go to Settings → Provider and set up a provider. The fastest path is hermes setup --portal in the CLI.
Sessions from CLI not showingThe desktop app shares the same session store. If sessions are missing, restart the desktop app.
Desktop app is slowClose other applications and check your internet connection.
Login failsMake sure you can sign in at hermes-agent.nousresearch.com; reset your password if needed.

How to Update

The desktop app updates alongside the CLI. Run in your terminal:

bash
hermes update

Next Steps

  • Read the CLI guide: the desktop app shares the same agent as the CLI. Learn more in the Hermes Agent CLI Beginner's Guide.
  • Connect messaging platforms: set up Telegram, Discord, Slack, or other platforms with hermes gateway setup.
  • Install plugins: add custom panes and commands to the desktop app.
  • Customize themes: change the app's appearance with skins and themes.
  • Explore the full documentation: visit hermes-agent.nousresearch.com/docs.
#Hermes#Desktop#Installation#Nous Research
Back to Tutorials

Related Tutorials