# Hermes Agent quickstart

> Install Hermes Agent, choose a model provider and start a first chat, following the official docs.

Canonical: https://hermeswatcher.com/start  
Note: Reflects the official Hermes Agent docs and GitHub README as read on 2026-10-20. The latest stable release at that time was v0.22.2 (Oct 15, 2026), with nightly canary builds on top. Commands and flags change quickly between releases, so check with hermes <command> --help.

## 1. 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.

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

## 2. 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.

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

## 3. 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.

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

## 4. 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.

```bash
hermes model
hermes setup --portal
hermes config set OPENROUTER_API_KEY sk-or-...   # replace sk-or-... with your own key, or skip this line
```

## 5. 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.

```bash
hermes
hermes --tui
```

## 6. 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.

```bash
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?"
```

## 7. Add tools and skills

Choose which toolsets are enabled on each platform, and browse the skills hub. Installed skills show up as slash commands.

```bash
hermes tools
hermes skills browse
hermes skills install <id>
```

## 8. 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.

```bash
hermes gateway setup
hermes gateway install
hermes gateway start
hermes gateway status
hermes pairing list
```

## 9. If something breaks

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

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

## Sources

- [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)
- [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation/)
- [Windows (WSL2) Quickstart](https://hermes-agent.nousresearch.com/docs/user-guide/windows-wsl-quickstart)
- [CLI Commands Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)
- [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt