How to run a first Hermes Agent chat

Hermes Agent is a terminal harness with its own installer, provider catalog, and session commands. The official quickstart is a short loop: install, choose one provider, finish one real chat, and prove you can resume it. Gateway, cron, skills, voice, and routing come later. The page's rule of thumb is blunt: if Hermes cannot complete a normal chat, do not add more features yet.

Install

On macOS or Windows, the recommended path is the Hermes Desktop installer. Download it from the Hermes website and run it. That installs the command-line and desktop applications together.

A command-line-only install is a different command. On Linux, macOS, or WSL2:

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

On native Windows, run this in PowerShell:

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

After that installer finishes, reload your shell:

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

aarch64 Android is not this installer. The quickstart sends that case to a separate Termux APT guide. Prerequisites and troubleshooting sit in the Installation guide linked from the same page. Python dependency commands on the quickstart use a PM-prepared source checkout; after a dependency change, reactivate the checkout and restart Hermes.

Choose a provider

The fastest-path table splits the first move by goal. If you just want Hermes working, run hermes setup, then run a real chat and verify it responds. If you already know the provider, run hermes model, save the config, and start chatting. A bot or always-on setup is hermes gateway setup, and only after the CLI chat works. A local or self-hosted model is hermes model, then a custom endpoint — verify the endpoint, model name, and context length. Multi-provider fallback is last: get the base chat working before you add routing.

Keep the Nous Portal one-command path separate from bring-your-own-key setup.

Nous Portal

On a fresh install, this is the documented easy path:

hermes setup --portal

That logs you in, sets Nous as the provider, and turns on the Tool Gateway in one command. The quickstart says one subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, and a cloud browser).

The same idea is Quick Setup inside hermes setup: OAuth login, no API keys to manage, a model plus the Tool Gateway tools, billed to your Nous Portal subscription. The docs call it the recommended fast path. Nous Portal OAuth is also available through hermes model.

Bring your own keys

Full Setup walks through every provider, tool, and option yourself. The catalog on the quickstart is the source of truth for env vars. A few rows from that table:

• OpenAI Codex uses device-code auth via hermes model, under ChatGPT or Codex Subscription.
• Anthropic is Claude directly: OAuth if you have a Max plan plus extra usage credits, or an Anthropic API key for pay-per-token.
• OpenRouter takes an API key.
• A custom endpoint (VLLM, SGLang, Ollama, or any OpenAI-compatible API) is a base URL plus an API key.

For a first chat, pick one provider and accept the defaults unless you know why you are changing them. You can switch later with hermes model. There is no lock-in. The full list lives on the Providers page linked from the quickstart.

Blank Slate is the third mode, and it is not the Portal shortcut. Everything starts off except the bare minimum: provider and model, the File Operations toolset, and the Terminal toolset. No web, browser, code execution, vision, memory, delegation, cron, skills, plugins, or MCP servers. Compression, checkpoints, smart routing, and memory capture are disabled. After that baseline you either finish with the minimal agent or walk through configurations and opt in. Blank Slate writes an explicit platform_toolsets.cli list plus agent.disabled_toolsets, so nothing you did not choose loads — not even after hermes update. Re-enable anything later with hermes tools, seed skills with hermes skills opt-in --sync, or tune settings with hermes setup agent.

hermes tools is how you configure which tools are enabled per platform. Use it after a working chat, not instead of one.

Context floor and where settings land

Hermes Agent requires a model with at least 64,000 tokens of context. Smaller windows cannot hold enough working memory for multi-step tool-calling workflows and are rejected at startup. The quickstart says most hosted models (Claude, GPT, Gemini, Qwen, DeepSeek) meet this easily. For a local model, set context to at least 64K — for example --ctx-size 65536 for llama.cpp or -c 65536 for Ollama.

Secrets and tokens go in ~/.hermes/.env. Non-secret settings go in ~/.hermes/config.yaml. The CLI puts the right value in the right file. The quickstart shows:

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

sk-or-... is the page's placeholder, not a key. Use the key your provider issued.

Start the chat

Two terminal interfaces share sessions, slash commands, and config. The classic one is the prompt_toolkit CLI. The newer TUI adds modal overlays, mouse selection, and non-blocking input. The quickstart recommends the TUI.

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

A welcome banner should show your model, available tools, and skills. Use a prompt that is specific and easy to verify. The page's examples are:

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.

Success, as the docs define it: the banner shows your chosen model and provider, Hermes replies without error, it can use a tool if needed (terminal, file read, or web search), and the conversation continues normally for more than one turn.

Empty or broken replies usually mean provider auth or model selection is wrong. Run hermes model again and confirm provider, model, and auth. A custom endpoint that returns garbage is often a wrong base URL, a wrong model name, or an API that is not actually OpenAI-compatible. Verify that endpoint in a separate client first.

Confirm resume

Before another layer, make sure the session saved:

hermes --continue    # Resume the most recent session

That should bring you back to the session you just had. If it does not, check that you are in the same profile and that the session actually saved. When hermes --continue cannot find an old session, the failure table points at hermes sessions list and the active profile.

When something feels off, the quickstart's recovery order is hermes doctor, then hermes model, then hermes setup, then hermes sessions list, then hermes --continue, then hermes gateway status. For a first chat, you should not need the gateway check.

Once the session is alive, type / for slash commands. Documented examples include /help, /tools, /model, /personality pirate, and /save. Alt+Enter and Ctrl+J add a new line in every terminal. Shift+Enter works only when the terminal sends it as a distinct sequence. To interrupt a long run, type a new message and press Enter, or use Ctrl+C.

Try this next

Open hermes or hermes --tui, send one of the three verify prompts above, and resume that session with hermes --continue. Stop there until the banner, the reply, and the resume all match. If they do not, walk the recovery commands in order and re-read the official quickstart before editing ~/.hermes/config.yaml by hand. If you would rather watch the same install-and-first-commands path, that page links an Onchain AI Garage masterclass, "Hermes Agent Masterclass: 1. Installation, Setup, Basic Commands," from Tonbi's AI Garage.

Sources

• Hermes Agent quickstart