Hermes Agent setup from the docs and source: install, auth, commands

A working Hermes Agent setup takes four commands: the installer for your system, hermes setup (or hermes model if you already know your provider), hermes to start a chat, and hermes -c to check that the session saved. Everything after that, from extra API keys to thinking level to session cleanup, is a handful of hermes subcommands and slash commands, listed in the cheat sheet below. Install and first commands; Quickstart path.

We put this guide together from the official documentation and the Python source of NousResearch/hermes-agent at revision 05d7b5af1c42d524762c7ffce991c1fe1aa2adb1 (26 October 2026). We have not installed or run Hermes on our machines. Every command here is copied from a docs page or a parser definition in the source, and each paragraph links the file and lines it came from. Where the docs and the code say different things, we say so. For what Hermes is and how its approvals work, start with our Hermes Agent review.

• The installer is curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash on Linux, macOS and WSL2, or a PowerShell one-liner on native Windows.
• hermes model is the main command for adding a provider or running OAuth. /model inside a chat can only switch between providers you already set up.
• The model needs at least 64,000 tokens of context. The source refuses to start below that, with one exception for LM Studio.
• Thinking level is /reasoning <level>, from none to ultra. It lasts for the session unless you add --global.
• hermes -z runs are marked unattended in the source, and that counts as YOLO, so one-shot script runs skip dangerous-command prompts.

Install Hermes Agent: the first step of Hermes Agent setup

Run the shell installer on Linux, macOS or WSL2: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. On native Windows the documented command, run in PowerShell, is iex (irm https://hermes-agent.nousresearch.com/install.ps1). Then reload your shell with source ~/.bashrc or source ~/.zshrc and type hermes. The docs also offer a desktop package for macOS and Windows; the macOS installer is Apple Silicon only. Install commands; After installation.

These are pipe-to-shell installers. Since we didn't run one, we can only report what the docs say it does: clone the source, bootstrap uv, and install pinned Python, Node.js, npm, ripgrep and FFmpeg, plus a pinned Chromium and the computer-use driver unless you pass --skip-browser or --skip-computer-use. On a terminal it asks for setup and gateway configuration; --non-interactive skips those stages. What the installer does; Pinned uv.

Before you start, have Git, curl, tar and a SHA-256 tool on the machine. Current installs run on Python 3.14, which the installer brings with it. With the shell script, code lands in ~/.hermes/hermes-agent/, the hermes wrapper in ~/.local/bin/, and your data in ~/.hermes/. If the shell says hermes: command not found, reload it or check PATH. Prerequisites; Install layout; Troubleshooting.

Hermes Agent setup wizard: Portal, Full Setup or Blank Slate

hermes setup on a fresh install offers three modes. Quick Setup logs you into a Nous Portal subscription with OAuth and switches on its hosted tools. Full Setup walks through every provider and tool with your own keys. Blank Slate turns on only a provider and model plus file and terminal tools; memory, skills, web, cron and plugins stay off until you enable them with hermes tools, and bundled skills come back with hermes skills opt-in --sync. If setup finds an OpenClaw, Claude Code, Codex CLI or Cursor folder, it first offers to import it. Setup modes.

You can also run one part of the wizard: the parser accepts model, tts, terminal, gateway, tools, telemetry and agent as sections, plus --quick, --reset, --non-interactive and --portal. On an existing install a bare hermes setup reruns the full wizard with your current values as defaults; --quick asks only for what is missing. Setup parser; Setup reference.

Then check the result the way the quickstart suggests. Start hermes (or hermes --tui), confirm the banner shows the model you picked, ask something with an answer you can verify, and continue for more than one turn. Exit, run hermes -c, and make sure you land back in the same conversation. If something breaks later, the documented recovery order is hermes doctor, hermes model, hermes setup, hermes sessions list, hermes --continue, hermes gateway status. First chat checks; Recovery toolkit.

Only once that works, add the next layer. hermes gateway setup connects Telegram, Discord, Slack, WhatsApp, Signal, email and other platforms, and hermes gateway status tells you whether it is running. To keep the agent's shell commands off your own machine, the quickstart's commands are hermes config set terminal.backend docker or hermes config set terminal.backend ssh; changing the value is the start of that setup, not proof the sandbox works. Gateway and sandbox; gateway status.

Hermes Agent provider and auth: hermes model, hermes auth add, .env

Run hermes model from your shell, not from inside a chat. The reference calls it the command for adding providers, entering keys and running OAuth flows. /model typed in a session can only switch between providers already configured, and by default only for that session; /model <name> --global saves the choice. hermes model vs /model.

Secrets go to ~/.hermes/.env and everything else to ~/.hermes/config.yaml. hermes config set picks the file for you: dotted keys such as terminal.backend go to YAML, and upper-case names such as OPENROUTER_API_KEY go to .env. Use hermes config get <key> to read a value back; it masks keys unless you pass --raw. Where settings live; config get and set.

hermes auth add is for a second or third credential on the same provider. It fills a credential pool that Hermes rotates through when one key hits a rate limit or billing cap. Credential pools. The documented forms are hermes auth add openrouter --api-key <key>, hermes auth add anthropic --type oauth, and hermes auth add openai-codex --type oauth --priority 0. The parser also takes --label, --no-browser and, for Codex only, --browser. Leave --api-key off and, per the parser's help text, Hermes prompts for the key, which keeps it out of your shell history. auth add parser; auth examples.

The other hermes auth subcommands are list, remove <provider> <index|id|label>, reset (clears cooldowns), priority, refresh, status <provider>, logout <provider> and upgrade. The documentation lists eight of these; upgrade, which signs you into a Nous account, is in the parser but not in that list. auth subcommands; Documented list.

Hermes Agent minimum context: the 64K floor and local models

Hermes needs a model with at least 64,000 tokens of context, and the source enforces it. MINIMUM_CONTEXT_LENGTH is 64_000, and at startup _enforce_minimum_context raises an error naming the model and its window if the window is smaller. The one exception is the LM Studio provider with an explicit positive model.context_length in your config. The constant; The check.

For a local server the window is whatever the server was started with, not what the model supports. The source's error message tells you to start llama.cpp with -c 64000, vLLM with --max-model-len, and Ollama with OLLAMA_CONTEXT_LENGTH=64000 or a Modelfile num_ctx, or to set model.ollama_num_ctx to the window the server really serves. For a hosted model that under-reports its window, set model.context_length to the real value. The quickstart gives -c 65536 as the Ollama example, which isn't the variable the source names, so follow the error text and Ollama's own docs. Minimum context in the quickstart; Error text.

Expect compression earlier than the user guide suggests on a small model. The configuration page shows compression.threshold: 0.50, but the compressor raises that to 75% for any model under 512,000 tokens, and never lets the trigger fall below 64,000 tokens unless that would pass 85% of the window. By that arithmetic a 128K model compresses near 96,000 tokens and a 64K model near 54,000, or less if output tokens are reserved. The developer guide documents the floor; the user configuration page doesn't. Neither page gives a RAM or disk minimum for the agent itself. Configuration page; Developer guide; The 75% floor; Trigger arithmetic.

If you were looking for how much space Hermes' own memory files use, that is a different limit: MEMORY.md and USER.md have character caps, and the prompt shows how full they are. Our Hermes Agent memory page covers it.

Set the Hermes Agent thinking level with /reasoning

Type /reasoning high in a chat to raise the thinking level for the rest of that session, or /reasoning high --global to save it as agent.reasoning_effort. Bare /reasoning shows the current level. The levels are none, minimal, low, medium, high, xhigh, max and ultra; show and hide toggle whether you see the model's thinking. Left unset, the configuration page says the level is medium. Reasoning effort; /reasoning usage.

The source agrees. The registry entry lists those eight levels plus the display toggles, and parse_reasoning_effort treats none, false and disabled as thinking off. A word it doesn't know gets an error in chat listing the valid levels, and changes nothing. The handler rebuilds the agent after a level change and writes the level to config only with --global; the display toggles show and hide are always saved. Registry entry; Parser; Handler.

Two other places set it. /model <name> --reasoning <level> changes model and effort in one step, with the same scope. At launch, the source accepts hermes --reasoning <level> for that run only, a flag missing from the reference's global options table. The provider may not accept every level: ultra is a Hermes label that each route clamps to its strongest real level. /model --reasoning; Launch flag; Clamping.

Hermes Agent session management: resume, name, prune

Every conversation is saved as a session in ~/.hermes/state.db. To pick one back up, hermes -c resumes the most recent session from that terminal, hermes -c "my project" resumes by title, hermes -r <id> by ID, and hermes --resume latest --in ./my-project the latest one for a folder. Resuming also changes into the session's recorded working directory unless you pass --no-restore-cwd. Sessions storage; Resume options; Resume flags.

Inside a chat, /new [name] starts a fresh session, /title <name> names the current one, /resume [name] and /sessions switch, and /branch copies the session so you can try another path. Titles are generated automatically after the first exchange if you don't set one. Session slash commands; Auto titles.

From the shell, hermes sessions list shows the last 20 (--limit, --source, --workspace filter it) and hermes sessions browse opens a searchable picker. hermes sessions rename <id> <title>, delete <id> and export <file> do what they say. hermes sessions prune with no filters deletes ended sessions older than 90 days; it skips pinned and archived ones, and --dry-run lists matches without deleting. sessions reference; prune parser.

When a long chat fills the context, /compress summarises it by hand; /compress here 4 keeps the last four exchanges word for word. With the default compression.in_place: true, compaction keeps the same session ID and archives the older turns inside it. /compress; In-place compaction.

Hermes Agent commands cheat sheet

Shell commands first, then the slash commands you type inside a chat. Each row links the parser line or registry entry it comes from.

The full lists are much longer: the CLI reference has over 60 top-level commands and the slash reference more than 80. CLI reference; Slash reference.

Hermes Agent setup options that turn confirmations off

Out of the box, approvals.mode is smart: a second model judges flagged shell commands, approves the low-risk ones, denies the clearly dangerous ones and asks you about the rest. Cron jobs, one-shot hermes chat --oneshot -q runs and webhook or API sessions default to deny, because nobody is there to answer. Our Hermes Agent review covers how to read these settings, and the architecture page shows where the check sits. Approval defaults; Approval modes.

These settings turn those prompts off:

• /yolo in a chat bypasses prompts for that session only, and the setting is saved with the session.
• hermes --yolo, or HERMES_YOLO_MODE=1 in the environment, covers every session in that Hermes process.
• hermes -z "<prompt>" marks its turn as unattended, and the YOLO check treats an unattended turn as YOLO. The shell-command guard runs that check before it looks at single_query_mode, so a -z run doesn't get the deny default that --oneshot -q runs get. Unattended turn; YOLO check; Command guard.
• cron_mode, single_query_mode or unattended_mode set to approve auto-approves in those contexts.
• approvals.mode: off, or /approvals off, covers every chat and cron job in that profile.
• approvals.destructive_slash_confirm: false stops /new, /clear and /undo from asking before they discard a conversation. Clicking Always Approve sets it.

YOLO scope; Three bypass sources.

Two things hold even under YOLO. The docs describe a hardline blocklist that YOLO doesn't skip, and your own approvals.deny patterns block a matching command under YOLO, mode: off and inside a container. hermes config set also refuses to write HERMES_YOLO_MODE to .env, so you can't turn YOLO on permanently that way. Deny rules; config set denylist.

Where the Hermes Agent setup docs and source disagree

We found five places where the setup documentation and the code at this revision say different things. None stops a setup from working, but each can confuse you when the screen doesn't match the page.

• Compression and session titles. The sessions guide says each compression starts a new session titled my project #2. The default compression.in_place: true keeps one session ID with no renumbering. Sessions guide; in_place default.
• /undo. The reference says it removes the last exchange. The registry says it backs up N user turns, one by default, and re-prompts. Docs; Registry.
• hermes -z and approvals. The parser's help text says approvals are auto-bypassed; the reference section on -z doesn't mention approvals. The delegation guide calls -z turns unattended, which a reader could take to mean unattended_mode: deny, the opposite of what the code does. Reference; Delegation guide.
• Setup sections and the reasoning flag. The parser takes a telemetry setup section and a --reasoning launch flag; the reference lists neither, and its section table also leaves out tts. Setup reference; Setup parser; Launch flag.
• Ollama context. The quickstart's example is -c 65536; the startup error names OLLAMA_CONTEXT_LENGTH or a Modelfile num_ctx. Quickstart; Error text.

FAQ

How long does Hermes Agent setup take? The installation page says under two minutes for the install. We haven't timed it. The provider step depends on whether you already have an API key or a subscription to sign into.

What is the difference between hermes model and hermes auth add? hermes model sets up a provider and picks your default model. hermes auth add adds another key or OAuth login to a provider you already use, so Hermes can switch keys when one runs out.

Can I use a local model with Hermes Agent? Yes, through a custom OpenAI-compatible endpoint, LM Studio or Ollama, as long as the server is started with at least a 64,000-token window. Below that, Hermes refuses to start, except on LM Studio when you set model.context_length explicitly.

How do I change the Hermes thinking level permanently? Run /reasoning <level> --global in a chat, or set agent.reasoning_effort in config.yaml. Without --global, the change ends with the session.

Where are my Hermes sessions stored, and how do I delete them? In state.db inside your Hermes home folder. Use hermes sessions delete <id> for one, or hermes sessions prune --dry-run to preview a bulk clean-up before running it for real.

Is there an official Hermes commands cheat sheet? The closest is the official CLI and slash command reference pages, both linked above. The table on this page is a short version taken from the same files and checked against the parser.