Your first hour with Hermes Agent

Install it, connect a model, and get one useful, checkable result. You do not need to understand the whole ecosystem first.

Install now Get a personal plan What is Hermes?

1. Install Hermes

Pick your platform. The official installer handles its own dependencies. Prefer an app? Hermes Desktop is available for macOS and Windows from the official site.

Easiest: download the Hermes Desktop app (Mac with Apple Silicon, or Windows 11). No terminal needed. Prefer the command line? Pick your system, then paste the command into Terminal (Mac, Linux) or PowerShell (Windows):

Install (Linux, macOS, WSL2)

Run the official install script, then reload your shell so the hermes command is on your PATH. The script clones the source, bootstraps its own pinned toolchain, and installs the latest stable release. Prefer a GUI? macOS and Windows users can download the Hermes Desktop installer from the Hermes website instead.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc   # or: source ~/.zshrc

Install (native Windows)

In PowerShell, run the Windows installer. Native Hermes runs shell commands through Git Bash, and the installer can fetch a pinned Git for Windows if Git is missing.

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

Or use WSL2 on Windows

Choose WSL2 if you want a full Linux environment, or if you need the dashboard's embedded terminal. Install WSL2 from an admin PowerShell, reboot, and check that your distro reports VERSION 2. Hermes does not run reliably on WSL1. Then run the Linux installer inside WSL. Keep your projects in the WSL home directory, not under /mnt/c.

wsl --install
wsl --list --verbose
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc

Full install guides: Windows · Mac · Linux · Docker · Run it 24/7

Chat with it from your phone: Telegram · Discord · WhatsApp

2. Connect a model and start chatting

2
Choose a model provider
Run the model picker to choose a provider and model. If you have a Nous Portal subscription, the fastest route is the Portal setup, which signs you in and enables the Tool Gateway (web search, image generation, TTS, cloud browser). You can also store API keys directly. Secrets go to ~/.hermes/.env and other settings to ~/.hermes/config.yaml. The model you pick needs a context window of at least 64K tokens.
```
hermes model
hermes setup --portal
hermes config set OPENROUTER_API_KEY sk-or-...   # replace sk-or-... with your own key, or skip this line
```
3
Start your first chat
Launch the classic CLI with hermes, or the newer TUI (recommended in the docs) with hermes --tui. Start with a concrete prompt you can check, such as asking it to summarize the repo you are in. Type / to see slash commands, and press Ctrl+C or send a new message to interrupt.
```
hermes
hermes --tui
```
4
Resume and one-shot tasks
Pick up your most recent session, or run a single query without opening the interactive UI. hermes -z prints only the final reply, which makes it handy in scripts.
```
hermes --continue
hermes chat --oneshot -q "Summarize this repo in 5 bullets and tell me what the main entrypoint is"
hermes -z "What changed in the last commit?"
```
5
Add tools and skills
Choose which toolsets are enabled on each platform, and browse the skills hub. Installed skills show up as slash commands.
```
hermes tools
hermes skills browse
hermes skills install <id>
```

3. Give it a small, checkable first job

The best first task has a clear input and a result you can check yourself in two minutes. These three are safe and useful:

Wake up to a useful research briefing

Example run includedResearch & knowledge work

Turn a defined set of sources into a short, dated briefing with evidence and a clear delivery check.

Carry project knowledge into the next session

Example run includedResearch & knowledge work

Keep decisions, source material, and next actions in durable project records that an agent can actually recover.

Build a useful GitHub issue review

Example run includedDevelopment & operations

Turn a bounded set of repository issues into a source-linked review with suggested next steps.

4. Optional: reach it from your phone

6
Optional: connect a messaging app
Run the interactive gateway setup for Telegram, Discord, Slack or another platform, then start the gateway. Installing it as a service keeps the bot and scheduled jobs running in the background. Unknown users are refused until you allowlist them or approve their pairing code.
```
hermes gateway setup
hermes gateway install
hermes gateway start
hermes gateway status
hermes pairing list
```

Read the gateway explained and who can talk to your bot before you share a bot link with anyone.

Before you leave it running

Know what it can touch. Read the security model and keep approvals on until you trust a workflow. Read more
Know what it costs. Check token usage with /usage and set limits before unattended jobs. Read more
Know where it lives. A laptop sleeps. Scheduled jobs need a machine that is awake. Read more
Know how to check it worked. A job being enabled is not proof it ran or delivered. Read more

If something breaks

The docs suggest this recovery order: run diagnostics, recheck the model and auth, rerun setup, then check sessions and gateway status.

hermes doctor
hermes model
hermes setup
hermes sessions list
hermes gateway status

Still stuck? Go to troubleshooting, which starts from the symptom you see.

Sources for this quickstart

Want Hermes set up for you?

Setup help, custom agent builds and one-off projects. Tell us what you need and get a quote by email.

Tell us what you need See services