Quickstart

This guide gets you from zero to a working Hermes setup that survives real use. Install, choose a provider, verify a working chat, and know exactly what to do when something breaks.

Onchain AI Garage put together a Masterclass walkthrough of installation, setup, and basic commands — a good companion to this page if you'd rather follow along on video. For more, see the full Hermes Agent Tutorials & Use Cases ↗ playlist.

<div style={{position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden', maxWidth: '100%', marginBottom: '1.5rem'}}> <iframe style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%'}} src="https://www.youtube-nocookie.com/embed/R3YOGfTBcQg" title="Hermes Agent Masterclass: Installation, Setup, Basic Commands" frameBorder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen

</iframe>

</div>

• Brand new and want the shortest path to a working setup
• Switching providers and don't want to lose time to config mistakes
• Setting up Hermes for a team, bot, or always-on workflow
• Tired of "it installed, but it still does nothing"

Pick the row that matches your goal:

Rule of thumb: if Hermes cannot complete a normal chat, do not add more features yet. Get one clean conversation working first, then layer on gateway, cron, skills, voice, or routing.

---

With the Hermes Desktop installer on macOS or Windows (recommended)

To easily install the command-line and desktop applications, download the Hermes Desktop installer ↗ from our website and run it.

Without Hermes Desktop:

For a command-line only install without Hermes Desktop, run:

Linux / macOS / WSL2 / Android (Termux)

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

Windows (native)

Run in powershell:

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

After it finishes, reload your shell:

source ~/.bashrc   # or source ~/.zshrc

For detailed installation options, prerequisites, and troubleshooting, see the Installation guide.

The single most important setup step. Use hermes model to walk through the choice interactively:

hermes model

Good defaults:

For most first-time users: choose a provider, accept the defaults unless you know why you're changing them. The full provider catalog with env vars and setup steps lives on the Providers page.

How settings are stored

Hermes separates secrets from normal config:

• Secrets and tokens → ~/.hermes/.env
• Non-secret settings → ~/.hermes/config.yaml

The easiest way to set values correctly is through the CLI:

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...

The right value goes to the right file automatically.

hermes            # classic CLI
hermes --tui      # modern TUI (recommended)

You'll see a welcome banner with your model, available tools, and skills. Use a prompt that's specific and easy to verify:

Summarize this repo in 5 bullets and tell me what the main entrypoint is.

Check my current directory and tell me what looks like the main project file.

Help me set up a clean GitHub PR workflow for this codebase.

What success looks like:

• The banner shows your chosen model/provider
• Hermes replies without error
• It can use a tool if needed (terminal, file read, web search)
• The conversation continues normally for more than one turn

If that works, you're past the hardest part.

Before moving on, make sure resume works:

hermes --continue    # Resume the most recent session
hermes -c            # Short form

That should bring you back to the session you just had. If it doesn't, check whether you're in the same profile and whether the session actually saved. This matters later when you're juggling multiple setups or machines.

Use the terminal

❯ What's my disk usage? Show the top 5 largest directories.

The agent runs terminal commands on your behalf and shows results.

Slash commands

Type / to see an autocomplete dropdown of all commands:

Multi-line input

Press Alt+Enter, Ctrl+J, or Shift+Enter to add a new line. Shift+Enter requires a terminal that sends it as a distinct sequence (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code terminal once the Kitty keyboard protocol is enabled). Alt+Enter and Ctrl+J work in every terminal.

Interrupt the agent

If the agent is taking too long, type a new message and press Enter — it interrupts the current task and switches to your new instructions. Ctrl+C also works.

Only after the base chat works. Pick what you need:

Bot or shared assistant

hermes gateway setup    # Interactive platform configuration

Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant, or Microsoft Teams.

Automation and tools

• hermes tools — tune tool access per platform
• hermes skills — browse and install reusable workflows
• Cron — only after your bot or CLI setup is stable

Sandboxed terminal

For safety, run the agent in a Docker container or on a remote server:

hermes config set terminal.backend docker    # Docker isolation
hermes config set terminal.backend ssh       # Remote server

For Docker sandboxes, you can also enable the egress credential-injection proxy so the sandbox never sees your real API keys — only opaque proxy tokens that work exclusively from behind a local TLS-intercepting daemon. See Egress proxy. Setup is hermes egress setup && hermes egress start; hermes setup terminal also points Docker users at it. Modal, SSH, Daytona, and Singularity are not wired yet.

Voice mode

# From the Hermes install directory (the curl installer placed it at
# ~/.hermes/hermes-agent on Linux/macOS or %LOCALAPPDATA%\hermes\hermes-agent on Windows):
cd ~/.hermes/hermes-agent
uv pip install --python ./venv/bin/python -e ".[voice]"
# Includes faster-whisper for free local speech-to-text

Then in the CLI: /voice on. Press Ctrl+B to record. See Voice Mode.

Skills

Skills are on-demand instruction documents that teach Hermes how to do a specific task — deploy to Kubernetes, open a GitHub PR, fine-tune a model, search for GIFs. Each is a SKILL.md file with a name, a description, and a step-by-step procedure. The agent reads the short descriptions for free and only loads a skill's full content when a task actually calls for it, so adding skills doesn't bloat every request.

Hermes ships with a catalog of bundled skills already installed in ~/.hermes/skills/. You can add more from the Skills Hub, or write your own.

Browse and install from the hub:

hermes skills browse                      # list everything available
hermes skills search kubernetes           # find skills by keyword
hermes skills install openai/skills/k8s   # install one (runs a security scan first)

The install argument is a source/path slug from the hub — openai/skills/k8s means the k8s skill from OpenAI's catalog. hermes skills browse shows the exact slugs to use.

Use a skill — every installed skill becomes a slash command automatically:

/k8s deploy the staging manifest          # run the skill with a request
/k8s                                       # load it and let Hermes ask what you need

This works in the CLI and in any connected messaging platform. You don't have to install everything up front — the agent picks the right bundled skill on its own during normal conversation when a task matches one.

See Skills System for writing your own, external skill directories, and the full hub source list.

MCP servers

# Add to ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Editor integration (ACP)

ACP support ships with the standard [all] extras, so the curl installer already includes it. Just run:

hermes acp

(If you installed without [all], run cd ~/.hermes/hermes-agent && uv pip install -e ".[acp]" first.)

See ACP Editor Integration.

---

These are the problems that waste the most time:

When something feels off, use this order:

1. hermes doctor
2. hermes model
3. hermes setup
4. hermes sessions list
5. hermes --continue
6. hermes gateway status

That sequence gets you from "broken vibes" back to a known state fast.

---

• CLI Guide — Master the terminal interface
• Configuration — Customize your setup
• Messaging Gateway — Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams, and more
• Tools & Toolsets — Explore available capabilities
• AI Providers — Full provider list and setup details
• Skills System — Reusable workflows and knowledge
• Tips & Best Practices — Power user tips
• Moving to another machine — hermes backup migrates your whole setup (or a single profile); no need to rebuild from scratch