Module 03 / Setup & Installation

Setup & Installation

A guided walkthrough covering installation, first-run configuration, model provider setup, and connecting a messaging channel.

Download Hermes Desktop Visit Hermes Docs
Learning Objectives
  • Install Hermes Desktop and complete the onboarding wizard.
  • Configure SOUL.md with a basic agent identity.
  • Connect a model provider, DeepSeek is the cheapest way in.
  • Pair Telegram by scanning a QR code, and optionally connect Discord.
Getting Started

Three Ways to Install

Config, keys, sessions, skills, and memory are shared across all three, so switching later isn't starting over.

★ Desktop App

A native chat app for macOS or Windows. Polished UI, no terminal needed. Today's starting point on those two.

Terminal

Direct, non-Docker install on your own machine. Same core as the Desktop App, just a CLI instead of a UI. The path for Linux, no desktop build exists yet.

VPS + Docker

Runs as a Docker container on a remote server, online 24/7 independent of your machine. The path to always-on workflows, covered in Module 08.

Installation

Installing Hermes (Desktop App)

On macOS or Windows, download the native app from hermes-agent.nousresearch.com and install it like any other app. First launch drops you straight into the onboarding wizard, covering inference provider, messaging, and tools in one pass.

On Linux, or prefer the CLI anyway?
Run curl -fsSL https://hermes-agent.nousresearch.com/install.sh | sh, then hermes setup. Same wizard, same result, just no window, and it writes into the identical ~/.hermes/ home folder.
First Run

First Run and SOUL.md

The setup wizard creates your ~/.hermes/ directory with a default SOUL.md.

Open ~/.hermes/SOUL.md (or hermes config edit). The default is generic, change it to something focused. A starting point for this course:

~/.hermes/SOUL.md: Financial Research Example
You are a financial research assistant focused on Indonesian equities.

Before answering any question about a specific stock or sector, always retrieve
live data from Sectors. Do not rely on training data for price, ratio, or
earnings information.

Format numbers in IDR where relevant. Keep responses concise unless the user
asks for a full breakdown. Always cite which tool you used to retrieve data.

Before executing any write operation (files, emails, calendar), confirm with
the user first.
↻ Read at the start of every conversation. Changes take effect immediately, no restart needed.
Model Provider

Connecting a Model Provider

During first run, the wizard asks for a provider. A few paths work for this course, pick whichever fits your budget.

★ DeepSeek

Grab a key from platform.deepseek.com and paste it in during setup. Chosen here for cheap experimentation, tool calling works well and the cost stays low for a full day of poking around.

Nous Portal

One OAuth login (hermes setup --portal) replaces separate OpenRouter, Anthropic, and OpenAI keys, 300+ models under one subscription. Comes with free credits, but activating the account requires a credit card on file.

Groq or Gemini

Both offer a genuinely free tier, no card needed. Create a key at console.groq.com for Groq, or aistudio.google.com for Gemini.

Another Direct API Key

OpenAI supports either OAuth login or an API key. Anthropic supports API key only, its OAuth login doesn't currently work with Hermes.

Messaging Channel

Connecting Telegram

Hermes talks to you through a messaging platform. From the Desktop App, Telegram is a QR scan away.

1
Open Messaging → Telegram

In the Desktop App, go to Capabilities → Messaging → Telegram.

2
Scan the QR code

The page shows a QR code. Open Telegram on your phone and scan it, following the prompts it gives you.

3
Restart the gateway

Config changes need a restart to apply. Use the app's restart control here, then confirm the "restart needed" badge clears before testing.

→ DM your bot once the restart is done.
Setting this up from the terminal or a VPS instead?
The QR flow is specific to the Desktop App. From the terminal or a VPS, you need a bot token from @BotFather and your Telegram user ID from @userinfobot, then hermes gateway setup.
Messaging Channel

Connecting Discord (Optional)

A few more steps than Telegram, worth it for the gotchas below, each of which has caused a bot to go silently unresponsive.

1
Create the application and bot

In the Discord Developer Portal, create an application. Under Bot → Privileged Gateway Intents, enable Message Content Intent. Copy the bot token.

2
Invite it to your server

Generate an invite URL from the Installation tab (bot scope, plus Send Messages, Read Message History, and View Channels, easy to miss). Open the URL, add the bot.

3
Configure Hermes

Capabilities → Messaging → Discord in the Desktop App, paste the bot token, Save. Get your own user ID via Developer Mode, right-click your name, Copy User ID.

!
Bot online but silent? Check Hermes's own allowlist first. Hermes drops every incoming message by default until an allowlist exists, even with every Discord permission correct. Fix: add DISCORD_ALLOW_ALL_USERS=true to the profile's .env for testing (or scope it with DISCORD_ALLOWED_CHANNELS / _USERS / _ROLES), then restart. This is the most common reason a correctly-configured bot looks broken.
Quick Reference

Full Setup Sequence

The complete flow from zero to a running Hermes agent.

  • 01Download and install Hermes Desktop, launch it
  • 02Complete the onboarding wizard, paste your DeepSeek API key when prompted
  • 03Edit ~/.hermes/SOUL.md with a focused identity
  • 04Capabilities → Messaging → Telegram, scan the QR code (and Discord, if wanted)
  • 05Restart the gateway to apply changes
  • 06DM your bot to confirm it responds, then head to Module 04 to connect Sectors