Getting Started with Hermes Agent — Install, Setup & First Conversation

Getting Started with Hermes Agent — Install, Setup & First Conversation

Hermes Agent··Updated ·19 min read·getting-startedinstallationhermes-agentquickstart

Install, pick a provider, and verify your first working Hermes Agent session.

What Changed Since We Last Wrote This

If you came here from an older version of this guide, two corrections matter up front.

First, the toolchain is different from what older copies stated. Current first-party installations run on Python 3.14. The broader >=3.11,<3.15 range in pyproject.toml only exists to let older installations run the updater before PM switches them over. It does not promise current runtime support on 3.11–3.13. More directly, the installer no longer advertises a hand-written Node.js version at all. PM provides pinned Python, Node.js, npm, ripgrep, and FFmpeg and selects those managed tool versions from pm/lock.json. The docs do not publish a Node.js version number, so this guide will not assert one.

Second, “it installed” is no longer the finish line. The goal of this refresh is verification. A working setup is the one that meets the quickstart’s definition of “working”: the banner shows your chosen model and provider, Hermes replies without errors, it can use a tool if needed, and the conversation continues for more than one turn. The quickstart then has you verify persistence with hermes --continue. With that in mind, we’ll take you from install to a resumed session, not just to a splash screen.

What Hermes Agent Is (and Isn’t)

Hermes Agent is a self-improving agent with its own CLI and TUI. The quickstart is clear about its scope: it’s not meant to be a coding copilot and not a thin chatbot wrapper. It’s designed to run in agentic workflows, with configurable toolsets and its own sessions. Depending on how you run it, it’s positioned to operate on infrastructure ranging from a small VPS up to serverless or cluster environments. For the purposes of this guide, treat those as vendor positioning, and focus on what you can actually verify on your own machine.

Step 1 — Pick Your Install Route

Before running any command, pick the route that matches your platform. The table below is built strictly from the installation page.

Method Where the code goes CLI entry point Default user data (HERMES_HOME) Notes
POSIX source script (Linux, macOS, WSL2) ~/.hermes/hermes-agent/ ~/.local/bin/hermes wrapper ~/.hermes/ Uses --dir to change the checkout independently from data. Running as root does not force an FHS layout unless you explicitly provide a path.
Windows source script (native PowerShell) %LOCALAPPDATA%\hermes\hermes-agent\ %LOCALAPPDATA%\hermes\bin\ %LOCALAPPDATA%\hermes\ Use -InstallDir and -HermesHome to control paths.
Desktop bundle (macOS/Windows) Inside the installed app package Packaged launchers; Windows execution aliases Platform default Hermes data directory Distributed as a packaged app. No separate “remote-only” Desktop download is listed.
Docker /opt/hermes/ Image entrypoint and hermes shim Mounted /opt/data/ Treat image/pull details as unlisted by this guide; only the layout is documented.
Termux APT (aarch64 Android) $PREFIX/lib/hermes-agent/ Symlinks in $PREFIX/bin/ ~/.hermes/ Its own repository path. The desktop/server scripts are not the Termux installation path.

Desktop packages (macOS & Windows)

If you want an app package instead of a shell script:

  • Windows: Download the package from the Hermes website, open the .appinstaller download with Windows App Installer. It installs the signed MSIX bundle and records its update source.
  • macOS: Open the DMG, then copy Hermes.app to Applications.

Important: The macOS installer is Apple Silicon only. macOS on x86 (Intel) processors is not a supported platform. If you’re on Intel macOS, do not assume compatibility from older guides.

The one-liner CLI install (Linux / macOS / WSL2 / native Windows)

This is the most common path and is what the installation page lists verbatim.

POSIX (Linux, macOS, WSL2):

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

Native Windows (PowerShell):

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

After the script finishes, reload your shell and start Hermes:

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

If you installed the CLI first and want the optional desktop app, run hermes desktop.

Android (Termux), Nix, and edge cases

  • Termux (aarch64): Configure its signed repository before running pkg install hermes-agent. Do not pipe the desktop/server scripts on Termux.
  • Nix: The installation page states Nix is no longer an explicitly supported install path (best-effort only). Note that the top-level docs index still lists “Nix & NixOS” in its marketing line. This guide does not resolve that tension — treat Nix as best-effort only and rely on hermes doctor if you go that route.
  • Non-sudo/service users: The docs note an admin can install prerequisites while a service user runs the curl installer, export PATH="$HOME/.local/bin:$PATH", run hermes doctor, and consider sudo loginctl enable-linger SERVICE_USER on applicable systems. Details may vary by distro, so treat as a pattern rather than a universal block.
  • Environment overrides: HERMES_HOME selects user data. On POSIX --dir selects the source checkout independently. On Windows use -HermesHome and -InstallDir.

What the Installer Actually Does Now

The installation page is explicit about the new flow, and it’s the reason the old “Python 3.11 + Node.js v22” claim is incorrect.

Installer flags worth knowing

Flag Purpose Notes
--channel main / -Channel main / HERMES_INSTALL_CHANNEL=main Install from the main channel New installs land on latest stable by default.
--skip-browser / -SkipBrowser Skip installing the pinned Chromium You can install later with hermes pm install chromium.
--skip-computer-use / -SkipComputerUse Skip cua-driver You can install later with hermes pm install cua-driver.
--include-desktop / -IncludeDesktop Include the desktop app during CLI install where applicable Optional.
--non-interactive / -NonInteractive Non-interactive runs On glibc Linux the installer may run the distro package manager to handle libatomic.so.1; it will not prompt in this mode.
--verbose / -Verbose / HERMES_INSTALL_VERBOSE=1 More verbose output Logged alongside logs/install.log.

Hermes remembers these choices: later installs and hermes update do not add them back. Also note: do not remove the data root to repair an application installation.

Step 2 — Choose a Provider and a Setup Mode

After install and reloading your shell, the next job is to get a working provider. The quickstart treats this as provider-first for a reason. Your secrets and settings live in two different places: secrets go to ~/.hermes/.env, non-secret settings go to ~/.hermes/config.yaml. You can manage them with commands like hermes config set model anthropic/claude-opus-4.6, hermes config set terminal.backend docker, hermes config set OPENROUTER_API_KEY sk-or-..., and hermes config get.

Before going further, know this hard constraint: Hermes requires a model with at least 64,000 tokens of context for agent use with tools. For local models you’ll need to raise context explicitly, e.g. --ctx-size 65536 (llama.cpp) or -c 65536 (Ollama). Smaller windows can be rejected at startup.

The 60-second path — hermes setup --portal

For first-timers, the fastest verified path is the Nous Portal.

hermes setup --portal

That command runs the Portal OAuth, lets you pick a Nous model, sets Nous as your inference provider in config.yaml, and turns on the Tool Gateway. In practice, one OAuth covers a model plus all four Tool Gateway tools, billed to your Nous Portal subscription. The Portal advertises “300+ frontier models, one bill” and “+ everything else | 280+ additional models — the full agentic frontier”. The Portal routes each model to the backend best suited for it — some through OpenRouter, others through proprietary or secondary providers, and routing for a given model can change over time. You can inspect this with hermes portal, hermes portal info/hermes portal status, hermes portal tools, and hermes portal open. The Tool Gateway covers web search, image generation, TTS, and a cloud browser; for image generation it lists “Nine models under one endpoint: FLUX 2 Klein 9B, FLUX 2 Pro, Z-Image Turbo, Nano Banana Pro (Gemini 3 Pro Image), GPT Image 1.5, GPT Image 2, Ideogram V3, Recraft V4 Pro, Qwen Image.” Treat those as the listed set at the time of writing.

Bringing your own keys — hermes model

If you’d rather bring your own keys, run

hermes model

This walks through the provider choice interactively outside of a session. You can switch providers at any time with no lock-in: inside a session, /model shows or changes the current model (/model <model> [--provider name] also works on the gateway CLI), while hermes model outside a session is the wizard for choosing your provider and model. The providers page lists representative options (by way of the quickstart): Nous Portal (OAuth via hermes model), OpenAI Codex (device code auth), Anthropic (OAuth requiring Max + extra credits, or an API key), OpenRouter (API key), Fireworks AI (FIREWORKS_API_KEY), Z.AI (GLM_API_KEY / ZAI_API_KEY, also Z_AI_API_KEY), Kimi / Moonshot (KIMI_API_KEY or KIMI_CODING_API_KEY), Kimi / Moonshot China (KIMI_CN_API_KEY), and Arcee AI (ARCEEAI_API_KEY). This is a representative set, not an exhaustive matrix, so rely on the providers page if you need to confirm a specific provider.

hermes setup modes

When you run hermes setup directly, you can choose between three modes as documented by the quickstart:

Mode What it does When to use it
Quick Setup (Nous Portal) OAuth login, no API keys to manage. Sets up a model plus the Tool Gateway tools, billed to your Nous Portal subscription. Fastest, recommended default for most first-timers.
Full Setup Walks through every provider, tool, and option yourself. You want to bring your own keys and configure each piece intentionally.
Blank Slate Everything starts off except the bare minimum needed to run an agent: provider & model, the File Operations toolset, and the Terminal toolset. No web, browser, code execution, vision, memory, delegation, cron, skills, plugins, or MCP servers — and compression, checkpoints, smart routing, and memory capture are all disabled. You want the strictest starting point and plan to enable features one by one. It writes an explicit platform_toolsets.cli list plus agent.disabled_toolsets, so nothing you didn’t choose ever loads — not even after hermes update. Re-enable with hermes tools, seed skills with hermes skills opt-in --sync, or tune with hermes setup agent.

Coming from Claude Code, Codex CLI, Cursor, or OpenClaw

If a fresh hermes setup finds OpenClaw, Claude Code, Codex CLI, Cursor or Grok Bot on the machine, it first offers to import that setup and installs the agent-importers plugin. The import guide lists the mapping: Claude Code’s CLAUDE.md becomes memory entries in ~/.hermes/memories/MEMORY.md; permissions.allow becomes command_allowlist; permissions.deny becomes approvals.deny; mcpServers becomes mcp_servers; skills/<name>/ imports to ~/.hermes/skills/claude-code-imports/<name>/; commands/*.md slash commands are “Skipped with a note — convert them into skills”. Codex CLI’s AGENTS.md and memories/*.md become memory entries, config.toml [mcp_servers.*] becomes mcp_servers, skills import to ~/.hermes/skills/codex-imports/<name>/. Cursor’s AGENTS.md plus rules/*.md/rules/*.mdc become memory, mcp.json becomes mcp_servers, skills import to ~/.hermes/skills/cursor-imports/<name>/. For machine moves you may also see hermes import / hermes profile import referenced by the flow — only act on what your setup actually offers.

Step 3 — Your First Conversation (Not Just hermes --tui)

Now for the part older guides left out: prove it actually works.

Classic CLI vs. TUI

You can start in either form. Both share the same sessions, slash commands, and config.

Interface Command Recommendation
Classic CLI hermes Great for scripting, single-query workflows, or minimal terminals.
Modern TUI hermes --tui Recommended by the quickstart. Has modal overlays, mouse selection, and non-blocking input.

Single-query mode is also available: hermes chat -q "Hello", hermes chat --query-file prompt.txt (or --query-file - for stdin with nothing shell-interpreted), hermes chat --model "...", hermes chat --provider ..., or hermes chat --toolsets "web,terminal,skills". When you run hermes chat, it discovers or starts the profile’s gateway (hermes gateway ensure), creates or resumes the session there, and attaches over the gateway’s local WebSocket. Closing the terminal detaches: “Detached; accepted work continues at the gateway. — it does not cancel the turn.

Run a prompt that proves it works

Use one of the verbatim suggested first prompts:

What's my disk usage? Show the top 5 largest directories.
Summarize this repo in 5 bullets and tell me what the main entrypoint is.

Check for these success criteria before moving to more features:

  1. The banner shows your chosen model and provider.
  2. Hermes replies without errors.
  3. It can use a tool if needed.
  4. The conversation continues normally for more than one turn.

Verify sessions persist — hermes --continue

This is the true finish line.

hermes --continue  # short: hermes -c

You can also resume explicitly: hermes --resume <session_id>, hermes --resume "my thread" by title, or hermes --resume latest. If resume fails, check whether you’re in the same profile and whether the session actually saved (hermes sessions list).

Five things worth knowing in minute two

  • Slash commands: /help (all commands), /tools (available tools), /model (switch models interactively), /personality pirate (try a personality), /save (save the conversation).
  • Multi-line input: Press Alt+Enter, Ctrl+J, or Shift+Enter. Alt+Enter and Ctrl+J work everywhere. Shift+Enter needs a terminal that sends it distinctly (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code once the Kitty keyboard protocol is enabled).
  • Interrupt: Type a new message and press Enter to interrupt the current task, or use Ctrl+C.
  • Gateway note: Some flows attach through the local gateway. Don’t panic if you see a detach message — work can continue at the gateway as documented.
  • Keep it simple first: The quickstart rule of thumb holds: if Hermes cannot complete a normal chat, do not add more features yet.

When It Breaks — The Recovery Toolkit

When something doesn’t look right, follow this ordered sequence:

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

Common failure modes

Symptom Likely cause Fix
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.

Extra gotchas from the docs

Quick reference

Command What it’s for
hermes Start chatting (classic CLI)
hermes model Choose your LLM provider and model
hermes tools Configure which tools are enabled per platform
hermes setup Full setup wizard
hermes doctor Diagnose issues
hermes update Update to latest version
hermes gateway Start the messaging gateway
hermes --continue Resume last session

What to Add Next — and in What Order

Resist the urge to enable everything at once. Follow a strict order:

  1. Verify first. Get a clean, multi-turn chat and confirm hermes --continue works.
  2. Tighten access. Only after step 1, configure tools deliberately with hermes tools. If you chose Blank Slate, enable only what you need.
  3. Extend. From there you can explore skills (hermes skills opt-in --sync), MCP, the messaging gateway, or hermes acp if relevant to your workflow.
  4. Stay aware of context. Keep the 64K minimum in mind, especially for local models.

If you ever need machine-readable references, the docs publish /llms.txt (~17 KB) and /llms-full.txt (~1.8 MB).

FAQ

Q: Do I need Python 3.11 or Node.js v22 to install Hermes Agent?
A: No. Current first-party installations run on Python 3.14. The >=3.11,<3.15 range only helps with the updater path. PM pins Python, Node.js, npm, ripgrep, and FFmpeg from pm/lock.json; the docs do not publish a Node.js version number, so don’t rely on a fixed v22 claim.

Q: Which install should I pick on macOS with Intel?
A: The macOS installer is Apple Silicon only. macOS on x86 (Intel) processors is not a supported platform. Check the installation page for current options before proceeding — this guide does not assume an Intel build exists.

Q: Can I install on Android/Termux or with Nix?
A: For Android (aarch64), use the signed APT repository and pkg install hermes-agent; the shell scripts are not the Termux path. For Nix, the installation page marks it as no longer an explicitly supported install path (best-effort only), despite the docs index still listing it. Treat Nix as best-effort.

Q: What’s the fastest way to get going without managing many API keys?
A: Run hermes setup --portal. It runs Portal OAuth, picks a Nous model, sets Nous as your provider, and turns on the Tool Gateway in one command — one OAuth covers a model plus all four Tool Gateway tools. Learn more via Nous Portal and portal.nousresearch.com.

Q: Where do I put API keys vs other settings?
A: Secrets go to ~/.hermes/.env, non-secret settings go to ~/.hermes/config.yaml. Use hermes config set and hermes config get to route values correctly. Also remember the 64,000-token context minimum for agent use with tools.

Q: How do I update or recover if it’s broken?
A: Use hermes update where applicable to your install method. For issues, run the recovery order: hermes doctor → hermes model → hermes setup → hermes sessions list → hermes --continue → hermes gateway status. See the failure table above. If HERMES_HOME is a symlink, hermes setup is not the repair — look to hermes doctor for storage problems.

The Bottom Line

Verdict: For most people reading this in late 2026, the correct move is the POSIX one-liner or Windows PowerShell one-liner (or a supported desktop bundle if you prefer an app), followed by hermes setup --portal to get a working provider and the Tool Gateway without juggling a long list of keys. If you want absolute minimalism, use Blank Slate and enable tools deliberately.

The habit that separates a “installed” box from a usable agent is this: run hermes --tui (or hermes), send one of the verbatim prompts, confirm the four success criteria, and verify persistence with hermes --continue. Ignore the old Python/Node version numbers — focus on the PM-pinned, Python 3.14-first flow and the recovery toolkit if anything drifts. Everything else is layering on top of a verified first conversation.

How This Guide Was Built

This guide is documentation synthesis only. Its commands, flags, paths, modes, tables and constraints come from the official Hermes Agent documentation pages listed below, checked on 2026-11-04; where the docs are silent, the gap is stated rather than filled. No commands were run hands-on on the reader’s behalf, and no “we tested” claims are made anywhere in this post. Where the docs are silent on a detail (for example, a published Node.js version number), it was omitted rather than guessed. Where the docs themselves show a known tension (notably Nix support vs. the docs index, and the narrow “not wired yet” egress-proxy statement vs. broader backend positioning), it was quoted narrowly or called out explicitly without attempting to resolve it. Marketing enumerations (e.g. “300+” models) are treated as vendor claims. Inline sources used: Installation, Quickstart, Docs Index, CLI, Nous Portal, Tool Gateway, Import from other agents, Providers, Skills, Messaging, Configuration, Package Management, FAQ, Nous Research, Nous Portal.

📖 Related Reads

  • ToolBrain — tool reviews, LLM comparisons, and AI workflow guides

Cross-links automatically generated from Hermes Tutorials.