Quickstart

This guide walks you through installing Hermes Agent, configuring a model provider, and starting your first conversation. After that, you can try terminal tools, slash commands, session recovery, messaging gateways, skills, and MCP integrations.

Prerequisites

• OS: Linux, macOS, or WSL2 on Windows.
• Model: An LLM with a long context window is recommended.
• API key: Prepare the API key for your chosen model provider, or an OpenAI-compatible endpoint.

1. Install

Linux / macOS / WSL2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Then reload your shell:

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

Windows

For most Windows users, WSL2 is still the recommended path: install WSL2, open an Ubuntu/WSL terminal, and run the Linux install command. WSL2 gives Hermes a Linux-like terminal environment, which tends to make dependency installation and project automation smoother.

2. Configure

The installer can guide you through model configuration. You can also rerun configuration at any time:

hermes model       # choose your LLM provider and model
hermes tools       # configure enabled tools
hermes setup       # run the full setup wizard

hermes model guides you through the model connection method: OAuth login, API key, or a custom OpenAI-compatible endpoint. For a custom endpoint, enter the base URL, API key, model name, and context window when prompted. You can rerun hermes model later to switch models without changing application code.

3. Start chatting

hermes

Hermes will show a welcome banner with the selected model, available tools, and loaded skills. Type a message and press Enter:

> What can you help me do right now?

Hermes ships with tools for web search, file operations, and terminal commands, so you can start with real tasks immediately.

4. Try the core workflows

Let Hermes use the terminal

> Check disk usage and list the five largest directories.

Hermes will run terminal commands on your behalf, explain the results, and continue if more investigation is needed.

Use slash commands

Type / in the chat to open command completion. Common commands:

Enter multiple lines

Press Alt+Enter or Ctrl+J to insert a newline. This is useful for pasting code, logs, or detailed prompts.

Interrupt a task

If Hermes is taking too long, type a new message and press Enter. Hermes will interrupt the current task and switch to the new instruction. Ctrl+C works too.

Resume a session

When you exit, Hermes prints a resume command. Later, run:

hermes --continue    # resume the latest session
hermes -c            # short form

5. Explore further

Use a sandboxed terminal

For stronger isolation, run commands in Docker or on a remote server:

hermes config set terminal.backend docker
hermes config set terminal.backend ssh

Connect messaging platforms

Use the gateway to talk to Hermes from WeChat, Feishu, QQ, Discord, WhatsApp, Signal, email, Home Assistant, and other channels:

hermes gateway setup

Enable voice mode

pip install "hermes-agent[voice]"
pip install faster-whisper    # optional local speech-to-text

Then enable voice in the Hermes CLI:

/voice on

Press Ctrl+B to record, or use /voice tts to have Hermes read replies aloud.

Browse and install skills

hermes skills search kubernetes
hermes skills search react --source skills-sh
hermes skills search https://mintlify.com/docs --source well-known
hermes skills install openai/skills/k8s

You can also manage skills with /skills in chat. Review third-party skills before installing them so you understand which tools and data they may access.

Use Hermes inside editors

Hermes can run as an ACP server for compatible editors:

pip install -e '.[acp]'
hermes acp

Connect MCP servers

Add external tools through Model Context Protocol by editing ~/.hermes/config.yaml:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Quick reference

Next steps

• Continue to Installation for more installation paths, Windows/WSL notes, and runtime backends.
• Read Features for the learning loop, skills, MCP, messaging gateway, and scheduled automations.
• Browse agentskills.io to discover community skills.