hermes-agent/website/docs/getting-started/quickstart.md

sidebar_position, title, description

sidebar_position	title	description
1	Quickstart	Your first conversation with Hermes Agent — from install to chatting in under 5 minutes

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.

Prefer to watch?

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.

Who this is for

• 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"

The fastest path

Pick the row that matches your goal:

Goal	Do this first	Then do this
I just want Hermes working on my machine	hermes setup	Run a real chat and verify it responds
I already know my provider	hermes model	Save the config, then start chatting
I want a bot or always-on setup	hermes gateway setup after CLI works	Connect Telegram, Discord, Slack, or another platform
I want a local or self-hosted model	hermes model → custom endpoint	Verify the endpoint, model name, and context length
I want multi-provider fallback	hermes model first	Add routing and fallback only after the base chat works

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.

---

1. Install Hermes Agent

Option A — pip (simplest):

pip install hermes-agent
hermes postinstall     # optional: installs Node.js, browser, ripgrep, ffmpeg + runs setup

PyPI releases track tagged versions (major/minor releases), not every commit on main. For bleeding-edge, use Option B.

Option B — git installer (tracks main branch):

# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Prefer native installers for desktop use?

• Desktop downloads: GitHub Releases

:::tip Android / Termux If you're installing on a phone, see the dedicated Termux guide for the tested manual path, supported extras, and current Android-specific limitations. :::

:::tip Windows Users Install WSL2 first, then run the command above inside your WSL2 terminal. :::

After it finishes, reload your shell:

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

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

2. Choose a Provider

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

hermes model

:::tip Easiest path: Nous Portal One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). On a fresh install:

hermes setup --portal

That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command. :::

Good defaults:

Provider	What it is	How to set up
Nous Portal	Subscription-based, zero-config	OAuth login via hermes model
OpenAI Codex	ChatGPT OAuth, uses Codex models	Device code auth via hermes model
Anthropic	Claude models directly — Max plan + extra usage credits (OAuth), or API key for pay-per-token	hermes model → OAuth login (requires Max + extra credits), or an Anthropic API key
OpenRouter	Multi-provider routing across many models	Enter your API key
Z.AI	GLM / Zhipu-hosted models	Set GLM_API_KEY / ZAI_API_KEY (also accepts Z_AI_API_KEY)
Kimi / Moonshot	Moonshot-hosted coding and chat models	Set KIMI_API_KEY (or the Kimi-Coding-specific KIMI_CODING_API_KEY)
Kimi / Moonshot China	China-region Moonshot endpoint	Set KIMI_CN_API_KEY
Arcee AI	Trinity models	Set ARCEEAI_API_KEY
GMI Cloud	Multi-model direct API	Set GMI_API_KEY
MiniMax (OAuth)	MiniMax frontier model via browser OAuth — no API key needed (model name in hermes_cli/models.py may change between releases)	hermes model → MiniMax (OAuth)
MiniMax	International MiniMax endpoint	Set MINIMAX_API_KEY
MiniMax China	China-region MiniMax endpoint	Set MINIMAX_CN_API_KEY
Alibaba Cloud	Qwen models via DashScope	Set DASHSCOPE_API_KEY (Qwen Coding Plan also accepts ALIBABA_CODING_PLAN_API_KEY)
Hugging Face	20+ open models via unified router (Qwen, DeepSeek, Kimi, etc.)	Set HF_TOKEN
AWS Bedrock	Claude, Nova, Llama, DeepSeek via native Converse API	IAM role or aws configure (guide)
Azure Foundry	Azure AI Foundry-hosted models	Set AZURE_FOUNDRY_API_KEY + AZURE_FOUNDRY_BASE_URL
Google AI Studio	Gemini models via direct API	Set GOOGLE_API_KEY / GEMINI_API_KEY
Google Gemini (OAuth)	Gemini via the google-gemini-cli OAuth flow — no key needed	hermes model → Google Gemini (OAuth)
xAI	Grok models via direct API	Set XAI_API_KEY
xAI Grok OAuth	SuperGrok / Premium+ subscription, no API key needed	hermes model → xAI Grok OAuth
NovitaAI	Multi-model API gateway	Set NOVITA_API_KEY
StepFun	Step Plan models	Set STEPFUN_API_KEY
Xiaomi MiMo	Xiaomi-hosted models	Set XIAOMI_API_KEY
Tencent TokenHub	Tencent-hosted models	Set TOKENHUB_API_KEY
Ollama Cloud	Managed Ollama-hosted models	Set OLLAMA_API_KEY
LM Studio	Local desktop app exposing an OpenAI-compatible API	Set LM_API_KEY (and LM_BASE_URL if non-default)
Qwen OAuth	Qwen Portal browser OAuth — no API key needed	hermes model → Qwen OAuth
Kilo Code	KiloCode-hosted models	Set KILOCODE_API_KEY
OpenCode Zen	Pay-as-you-go access to curated models	Set OPENCODE_ZEN_API_KEY
OpenCode Go	$10/month subscription for open models	Set OPENCODE_GO_API_KEY
DeepSeek	Direct DeepSeek API access	Set DEEPSEEK_API_KEY
NVIDIA NIM	Nemotron models via build.nvidia.com or local NIM	Set NVIDIA_API_KEY (optional: NVIDIA_BASE_URL)
GitHub Copilot	GitHub Copilot subscription (GPT-5.x, Claude, Gemini, etc.)	OAuth via hermes model, or COPILOT_GITHUB_TOKEN / GH_TOKEN
GitHub Copilot ACP	Copilot ACP agent backend (spawns local copilot CLI)	hermes model (requires copilot CLI + copilot login)
Custom Endpoint	VLLM, SGLang, Ollama, or any OpenAI-compatible API	Set base URL + API key

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.

:::caution Minimum context: 64K tokens Hermes Agent requires a model with at least 64,000 tokens of context. Models with smaller windows cannot maintain enough working memory for multi-step tool-calling workflows and will be rejected at startup. Most hosted models (Claude, GPT, Gemini, Qwen, DeepSeek) meet this easily. If you're running a local model, set its context size to at least 64K (e.g. --ctx-size 65536 for llama.cpp or -c 65536 for Ollama). :::

:::tip You can switch providers at any time with hermes model — no lock-in. For a full list of all supported providers and setup details, see AI Providers. :::

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.

3. Run Your First Chat

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:

:::tip Pick your interface Hermes ships with two terminal interfaces: the classic prompt_toolkit CLI and a newer TUI with modal overlays, mouse selection, and non-blocking input. Both share the same sessions, slash commands, and config — try each with hermes vs hermes --tui. :::

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.

4. Verify Sessions Work

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.

5. Try Key Features

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:

Command	What it does
/help	Show all available commands
/tools	List available tools
/model	Switch models interactively
/personality pirate	Try a fun personality
/save	Save the conversation

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.

6. Add the Next Layer

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

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

---

Common Failure Modes

These are the problems that waste the most time:

Symptom	Likely cause	Fix
Hermes opens but gives empty or broken replies	Provider auth or model selection is wrong	Run hermes model again and confirm provider, model, and auth
Custom endpoint "works" but returns garbage	Wrong base URL, model name, or not actually OpenAI-compatible	Verify the endpoint in a separate client first
Gateway starts but nobody can message it	Bot token, allowlist, or platform setup is incomplete	Re-run hermes gateway setup and check hermes gateway status
hermes --continue can't find old session	Switched profiles or session never saved	Check hermes sessions list and confirm you're in the right profile
Model unavailable or odd fallback behavior	Provider routing or fallback settings are too aggressive	Keep routing off until the base provider is stable
hermes doctor flags config problems	Config values are missing or stale	Fix the config, retest a plain chat before adding features

Recovery Toolkit

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.

---

Quick Reference

Command	Description
hermes	Start chatting
hermes model	Choose your LLM provider and model
hermes tools	Configure which tools are enabled per platform
hermes setup	Full setup wizard (configures everything at once)
hermes doctor	Diagnose issues
hermes update	Update to latest version
hermes gateway	Start the messaging gateway
hermes --continue	Resume last session

Next Steps

• 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