Install and first chat
#

Goal: from zero to a verified chat. Do not add messaging bots, cron, or custom tools until this works.

1. Install
#

Desktop installer (macOS / Windows)
#

Download the Hermes Desktop installer from the project site and run it. That path installs CLI + desktop together.

CLI-only — Linux / macOS / WSL2 / Termux
#

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Reload your shell afterward:

source ~/.bashrc   # or ~/.zshrc

CLI-only — Windows (PowerShell)
#

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Verify the binary
#

hermes --help

2. Choose a provider
#

Pick the path that matches you:

Goal	First command	Then
Fastest first-time setup	`hermes setup` (often with portal/OAuth options)	Chat once
You already know the provider	`hermes model`	Save config, then chat
Local / self-hosted endpoint	`hermes model` → custom endpoint	Check model name + context length
Always-on messaging bot	Finish CLI chat first	Then `hermes gateway setup`

Rule: if Hermes cannot complete a normal chat, stop and fix that before stacking features.

3. First conversation
#

Start the CLI:

hermes

Or a one-shot query:

hermes -q "Reply with exactly: hermes-ok"

You want a real model reply, not a credential or routing error.

If it fails
#

Re-run hermes model / hermes setup and confirm the provider credentials
Check that secrets live in ~/.hermes/.env (or your profile’s home), not only in a random shell export
Read logs under ~/.hermes/logs/ (agent.log, errors.log) — or hermes logs

Profiles use get_hermes_home(); with hermes -p <name> the home is that profile’s directory, not always ~/.hermes.

4. Optional: messaging (after CLI works)
#

hermes gateway setup

Connect Telegram, Discord, Slack, or another platform only when CLI chat is already green.

Expected outcome
#

hermes starts without import/config crashes
At least one user → assistant exchange completes
You know where config and logs live for your active home

Next
#

CLI and config basics

Install and first chat#

1. Install#

Desktop installer (macOS / Windows)#

CLI-only — Linux / macOS / WSL2 / Termux#

CLI-only — Windows (PowerShell)#

Verify the binary#

2. Choose a provider#

3. First conversation#

If it fails#

4. Optional: messaging (after CLI works)#

Expected outcome#

Next#

Further reading#