Hermes Agent, set up safely
By the end of this page you will have a WORKING HERMES: installed, connected to a model, proven with a real conversation, and set up so it asks permission before doing anything consequential.
Written against Hermes v0.21.0, “The Pantheon Release” (tag v2026.8.31, released 2026-08-31).§17 Releases land often and carry hundreds of changes each, so if a screen does not match this page exactly, check your version before assuming you did something wrong.
The path — you may stop at the star
Understand · MODEL ≠ AGENT · read this first
MODEL is not the AGENT
Hermes is the agent. Grok, Claude, Gemini and the rest are models you plug into it.
Almost everyone arrives thinking they are about to “install an AI.” That is not what happens. You install one thing (the agent) and then plug a second, separate thing into it (the model). They come from different companies, they are paid for separately, and either one can be swapped without touching the other.
The mainstream providers a new user will meet in the setup path include Nous Portal (a free sign-in that opens 300+ models), Anthropic (Claude), OpenAI (including Codex), OpenRouter, and Google (Gemini). Others exist and more are added over time; the current picker is the source of truth.§28
The agent (installed on your computer)
- The agent is the program that runs on your computer. It is the part with hands: it can read and write files, run commands, and use whatever tools you connect. It holds your settings and it is the thing actually installed on your machine.
- It owns the settings file and the secrets file: ~/.hermes/config.yaml and ~/.hermes/.env on macOS, Linux and Windows-through-WSL2; %LOCALAPPDATA%\hermes\config.yaml and %LOCALAPPDATA%\hermes\.env on native Windows.§6
- It owns the permission rules that decide what it may do without asking you first.§7
The model (the thinking, at a provider)
- The model is the thinking. It does not live on your computer by default. It lives at a provider, you connect to it over the internet, and that provider bills you for what you use.
- The model has no hands. It reads what the agent gives it and writes back what it thinks should happen next. The agent turns that into action.
Why the split is good news
You can change your mind about the model without reinstalling anything. Hermes ships an interactive selector for exactly this.§14
Your setup survives the swap. Settings, permission rules and connections belong to the agent, not the model.§6, §7
The bill splits too. Hermes itself and the model provider are separate lines.
The one real constraint
Not every model qualifies. Hermes requires a model with at least 64,000 tokens of context and rejects smaller windows at startup. If Hermes refuses a model, the fix is a bigger-context model, not a reinstall.§15
“Installing Hermes installs an AI.”
It installs the worker. You connect the thinking separately, and until you do there is nothing to talk to.
“If it runs on my machine, my machine is doing the thinking.”
By default, no. The agent runs locally and sends work to a provider. Running the thinking on your own hardware is a later, optional path with nothing to do with which operating system you chose.
“The model can reach my files, so the model is the risk.”
The model proposes; the agent acts. Your safety controls live on the agent side: what it may do unattended, where it may write, and what it must ask you about first. That is why the security baseline is a section, not a footnote.§7, §10
How do I know this landed?
You do not need to install anything to check. Answer these three out loud:
- Which of the two is installed on your computer, and which one lives at a provider you connect to?
- If you switch models next month, does your Hermes configuration survive?
- When Hermes writes a file on your machine, which of the two performed that action?
Answers: The agent is installed locally and the model is remote by default; yes, your configuration survives because it belongs to the agent; the agent performed it.
You may stop at WORKING HERMES
WORKING HERMES is a complete, valid, finished outcome. It is not a trial version, not a half-install, and not a stepping stone you are obligated to leave. Everything past it (a chat app, an inbox, a browser, running the thinking on your own hardware) is optional, additive, and separately reversible.
Keep these two questions apart
Question 1
“Which operating system am I on?”
This decides your install command and where your settings file lives. It is Section 1.
Question 2
“Can my computer run a model locally?”
A hardware question (memory, chip, storage) and a later, optional topic. It does not change your install command or your operating system. A modest laptop on any supported platform runs a perfectly good WORKING HERMES, because the thinking happens at the provider.
Our own tested example is an Apple Silicon Mac mini M4. That install was made on an older release (v0.14.0) and is used only to corroborate, never to set current wording; this page is written against v0.21.0.§18, §17
Choose your platform
Goal
You know which supported platform you are on, whether it is fully supported or best-effort, and which install branch in Section 2 is yours. Nothing is installed yet. This section is a decision, not an action on your machine.
Prerequisites
- None. This is the first step.
- You need to know two things about the computer in front of you: its operating system, and, if it is a Mac, whether it has an Apple Silicon chip (M1, M2, M3, M4 and later) or an older Intel chip.
Exact user action
Read the tiers and write down which of these you are: macOS, Windows (native or WSL2), or Linux. That choice is what you carry into Section 2, and it is also what the selector at the top of this page switches. Docker is a supported path this page does not walk yet.
Tier 1, fully supported (Nous Research states it strives to never break installations and updates for these): macOS on Apple Silicon; Windows 10 and 11 (x86_64, aarch64); Linux and WSL2 (x86_64, aarch64); Docker (x86_64, aarch64).§1
Tier 2, best-effort (releases may break things): Android/Termux (aarch64), and Nix.§1
Unsupported: Intel Macs, AUR, PyPI, and Homebrew.§1
An Intel Mac is not a supported platform. If About This Mac shows an Intel processor, this path has no supported route for you on that machine. Use a different, supported computer. (Docker is also a supported path, but this page does not walk it yet.)§1
Do not install via Homebrew, even if a brew formula appears to exist. It is listed as unsupported.§1
Where
Nowhere yet. This is a decision made away from the keyboard, with one lookup.
Apple menu, then About This Mac, and read the chip line for “Apple M” or “Intel.”
Expect to see
One of the tier lists containing your machine. Your platform appears in Tier 1, in Tier 2, or in the unsupported list.
If your machine is Tier 2 or unsupported, you found that out now, at zero cost, instead of forty minutes into a failing install. That is a good outcome for this section.
Save / apply
Nothing to save. No file is written and no setting is changed. Write your one word down somewhere you will still have it in five minutes.
Verify success
Answer both, and be specific:
- Name your platform in the exact words the tier list uses (for example “macOS on Apple Silicon”, “Windows 11, x86_64”, or “Linux, x86_64”).
- State its tier: fully supported, best-effort, or unsupported.§1
- Pass condition: you can say both without going back to look. If you cannot name the tier, you have only read the list, not made the decision.
Common friction
Security / privacy
What this step exposes
Not applicable to the decision itself: nothing is installed, nothing is transmitted, and no credential exists yet.
Forward-looking note: your platform decides where your secrets will be stored on disk (%LOCALAPPDATA%\hermes\.env on native Windows, ~/.hermes/.env on macOS, Linux and WSL2), and native Windows does not get the command-content scanning layer, because that component has no prebuilt Windows binary and is silently skipped there. Silently means you will not be warned. It is the strongest argument for WSL2 over native Windows if you have a free choice.§6, §9
Next safe step
Go to Section 2, Install Hermes, with the selector at the top of this page set to the platform you wrote down.
How do I know this worked?
- You can name your platform in the same words the tier list uses.
- You know whether that platform is Tier 1, Tier 2, or unsupported.§1
- You know which install branch in Section 2 is yours.
- You have not confused “which operating system” with “can my machine run a model locally.”
If any line is untrue, go back to Verify success and then Common friction above before continuing.
Install Hermes
Goal
The Hermes agent is installed on your machine and responds when you call it. It has no model connected yet, so it cannot think or answer questions. That is expected: you installed the worker, and the thinking arrives in Section 3.
Prerequisites
- Section 1 complete: you know your platform and its tier.
- A working internet connection, since the installer downloads from the internet.
- Permission to install software on this machine. On a work-managed laptop this is the step that quietly blocks people, so check before you begin.
Exact user action
Use only the branch for your platform. Do not mix branches.
A Hermes Desktop app exists as an alternative to the command-line installer on macOS and Windows. If you would rather take that path, the recommended install is the Hermes Desktop installer, downloaded from the Hermes website and run: it installs both the command-line and desktop apps in one step, and after a CLI-only install the desktop app can be launched with hermes desktop. The same read-before-run caution as the shell installer below applies to any installer binary obtained from the website. This guide uses the command-line path throughout, because everything after this point (checking config, running diagnostics, setting security keys) is written in commands.§2, §3, §26
Step 1 · Download the installer to disk (do not pipe it into a shell)§2, §4
curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o /tmp/hermes_install.shNow open /tmp/hermes_install.sh and read it. Any text editor will do; in the terminal, less /tmp/hermes_install.sh shows it and q closes it. You do not need to understand every line. You are looking for anything that is obviously not an installer: a different domain than the one you typed, or something being uploaded rather than downloaded.
Step 2 · Run it§2, §4
sh /tmp/hermes_install.shDownloading first means the script can be read, and hashed, before it executes. The official one-liner pipes it straight into a shell, which runs it before any human has seen it. This is the recommended pattern and it costs you thirty seconds.
Docker is also a Tier 1 install path, meaning Hermes itself runs inside a container, obtained with docker pull. Two things to know: Docker installs cannot use hermes update (you pull a new image instead), and this is not the same thing as the terminal.backend: docker sandbox setting, which isolates tool execution for an already-installed Hermes and belongs in Advanced.§5, §12
Where
Terminal (Applications, then Utilities, then Terminal).
Where the files land (you will need this in Sections 3 and 5): ~/.hermes/ (the ~ means your home folder).§6
Expect to see
Installer output scrolling in your terminal, ending without an error, and returning you to a normal prompt.
Judge it by shape rather than exact wording: work happening, then a clean return to your prompt, with no line saying the install failed or aborted. A wall of text is normal. If it ends and you can type again, go to VERIFY SUCCESS, which is the real test.
Save / apply
Nothing to save by hand. The installer writes what it needs.
Easy to miss: close your terminal and open a new one before verifying. A freshly installed command is often not visible to a shell that was already open, which produces a “command not found” that looks like a failed install but is only a stale session.
Verify success
In a new terminal, run the built-in diagnostic. It checks config and dependency issues.
Run the diagnostic§11
hermes doctorIf it reports fixable problems, attempt automatic repairs§11
hermes doctor --fixConfirm the installed version§25, §17
hermes --versionhermes -V and the hermes version subcommand print the same. Expect a single line naming Hermes Agent and a version number. If it is older than the current release, that is a hermes update step, not a failed install.
- The command is found. It runs and produces output rather than “command not found.” That alone proves Hermes is installed and reachable, which is what this section was for.
- It reports on your configuration. Complaints about a missing or unconfigured model are expected right now, because you have not connected one yet. That is Section 3’s job.
Common friction
Security / privacy
What this step exposes
This step runs code from the internet with your user’s permissions. That is what an installer is.
Read before you run, where you can. Download-then-run exists so the script can be read and hashed before it executes, and it is the recommended pattern on macOS, Linux, and Windows through WSL2. On native Windows you currently cannot: only the piped form is confirmed to exist.§2, §4, §3
Nothing secret exists yet. No API key, password, or token has been created or stored. The credential surface opens in Section 3, and Section 5 is where it gets locked down.
Next safe step
Go to Section 3, Choose and connect a model. Stopping here is safe but not useful: you have a worker with nothing to think with. Section 3 is short.
How do I know this worked?
- hermes doctor runs in a new terminal and does not report “command not found” (or PowerShell’s “not recognized”).§11
- The install ended without an error and returned you to a normal prompt.
- You know where your config and secrets will live for your platform: %LOCALAPPDATA%\hermes\ on native Windows, ~/.hermes/ on macOS, Linux, and WSL2.§6
- You understand that model-related complaints from hermes doctor are expected at this point.
If any line is untrue, go back to Verify success and then Common friction above before continuing.
Not yet verified6 details this guide will not guess at
- Minimum disk space, memory, and OS-version requirements for installing Hermes, and whether the macOS install path needs an administrator password or Xcode command line tools.
- An exact, pinned download URL and filename for the Hermes Desktop installer, and a screenshot-level per-OS click-through of it.
- The exact Docker image name and tag to pull, and the exact docker run invocation including volume mounts for config and secrets.
- The exact success output text of install.sh and install.ps1.
- Whether install.ps1 needs an Administrator PowerShell, which PowerShell versions it supports, and whether it updates PATH for new windows.
- The exact output format of hermes doctor, including how checks are labelled on screen.
Choose and connect a model
Goal
A model provider is connected and your credentials are stored, so Hermes has something to think with. This is the moment the installed worker from Section 2 becomes capable of answering you.
Prerequisites
- Section 2 complete: hermes doctor runs.
- You have read MODEL is not the AGENT above. This section is where the distinction stops being theoretical.
- An account with a model provider, and usually a payment method on that account. This is billed by the provider, not by Hermes.
- The model must have a context window of at least 64,000 tokens. Hermes rejects smaller windows at startup. Check this before you pay for anything.§15
- The mainstream providers a beginner will meet include Nous Portal (a free sign-in that opens 300+ models), Anthropic, OpenAI (including Codex), OpenRouter, and Google. Their default modern chat models comfortably exceed the 64,000-token minimum, and the operational rule is simpler than a table: pick a provider in the selector, and if the chosen model is under the floor, Hermes rejects it at startup rather than starting a session that will fail later.§28, §15
Exact user action
Run hermes model, the dedicated model selector. It is interactive, and it handles adding providers, running sign-in flows, and entering API keys. Follow the prompts to pick your provider and model, and supply your credential when asked. The two commands after it are alternatives, not extra steps: hermes setup --portal if you want the free Nous sign-in with nothing to paste, and hermes setup if you want the full wizard.§14
The model selector (narrowest tool)§14
hermes modelFastest working chat, no keys to paste (Quick Setup via Nous Portal)§27
hermes setup --portalThe full setup wizard (model, tts, terminal, gateway, tools, agent in one flow)§13
hermes setupIf you run hermes setup, choosing one of its three modes is its first prompt. Quick Setup (Nous Portal): a free OAuth sign-in with no API keys; it configures a model and the Tool Gateway for you, and it is the fastest working-chat path in this guide. Full Setup: walks every provider, tool, and option with your own API keys, for deliberate control. Blank Slate: everything off except provider and model, File Operations, and the Terminal toolset, written to config explicitly so nothing you did not choose loads, even after a later hermes update; you re-enable tools deliberately with hermes tools afterwards.§27
Read every prompt before you answer it. On a real install, a stray value left over from an earlier attempt landed in a free-text “AWS Region” prompt, silently pointing the model endpoint at AWS Bedrock with no credentials configured. Hermes then failed with could not resolve credentials from session on every run until the provider was explicitly re-selected. That was observed on v0.14.0 and is not confirmed to reproduce on the current version. Treat it as a risk pattern worth watching for, not a bug to expect.§19
Where
In your terminal, in the same environment where you installed Hermes in Section 2.
Part of this happens outside your terminal: creating your provider account, and copying an API key from the provider’s website. If the provider uses a sign-in flow instead of a pasted key, hermes model runs that flow for you.§14
Where the credential ends up: API keys land in the .env secrets file, ~/.hermes/.env. Settings (which model, and everything else) go to config.yaml in the same folder. Settings in one file, secrets in the other.§14, §6
Expect to see
An interactive selector: a list of providers, then a model choice, then either a request for an API key or a sign-in flow. It ends by returning you to your prompt.§14
If you chose a model with a context window under 64,000 tokens, expect a rejection at startup rather than a warning you can ignore.§15
Save / apply
The selector writes your choices for you: settings into config.yaml and the credential into .env. There is no separate save button and no file to edit by hand.§6, §14
Do not hand-edit either file at this stage. If something is wrong, run the selector again. Re-selecting the provider explicitly is the documented recovery from a bad configuration state.§19
Verify success
Run the diagnostic again.
Diagnostic§11
hermes doctorIf problems remain and look fixable, hermes doctor --fix attempts automatic repairs.
- Pass condition: the model-related complaints you saw at the end of Section 2 are gone. That change is the proof this section worked. The full proof is Section 4, where you actually talk to it.
Common friction
Security / privacy
What this step exposes
This is the step that creates a real secret. Your API key is written to the .env file in your Hermes folder. Anyone who can read that file can spend money on your provider account as you. Treat it as you would a saved credit card.§14, §6
Never paste an API key into a plain terminal window to “check” it. On a real setup session a token was briefly pasted into a plain terminal by mistake before being entered correctly; nothing broke, but the token was on screen. Screens get shared, recorded, and shoulder-read. Enter credentials only into the prompt that asked for them. If a key is ever exposed, revoke and regenerate it at the provider immediately.§20
Understand the data path: your prompts, and whatever the agent includes as context, go to your model provider over the internet. If that is unacceptable for some category of your work, the local-model option under Go further is the honest answer, and it is a hardware question, not an operating-system one.
Next safe step
Go to Section 4, First successful conversation, and prove this actually works. Stopping here is safe but unproven: a configuration that looks right and has never been tested.
How do I know this worked?
- hermes doctor no longer complains about a missing or unconfigured model.§11
- You know which provider you connected and which model you selected.
- You confirmed that model’s context window is at least 64,000 tokens.§15
- You know your API key is stored in the .env file in your Hermes folder, and where that folder is on your platform.§6, §14
- Your key was never displayed in a plain terminal window.§20
If any line is untrue, go back to Verify success and then Common friction above before continuing.
Not yet verified2 details this guide will not guess at
- A per-model context-window table listing which specific models within each provider meet or exceed 64,000 tokens (windows change per provider release, so the guide teaches the floor and the startup rejection instead).
- The exact prompt wording, prompt order, and on-screen labels of hermes model and of each hermes setup mode.
First successful conversation
Goal
You have talked to Hermes and it answered. Installation and configuration are now proven rather than assumed, and you have seen with your own eyes that the agent and the model are connected.
Prerequisites
- Sections 2 and 3 complete: Hermes installed, a model connected, hermes doctor not complaining about the model.
- An internet connection, since the model is remote.
- Two minutes.
Exact user action
Start Hermes and ask it something trivial.
Start an interactive chat session§22
hermesWith no subcommand, Hermes launches its chat command by default; hermes chat is the explicit equivalent. If you would rather arrive with your question ready, hermes chat -q "your question" opens the session with that question as the first turn and stays open. (On older releases -q answered and exited; --oneshot is the flag for that behavior today.)
Launch the TUI (full-screen terminal interface) instead§16, §23
hermes --tui--tui is equivalent to setting HERMES_TUI=1, and --tui always wins over the display.interface config setting when both are present.
Force the classic CLI explicitly§16
hermes --cliHermes has two interfaces. The classic CLI (a banner, then an interactive prompt with / slash-command autocomplete) is the default. The TUI is opt-in.§23
Once it is running, ask for something small and harmless: “What model are you using right now?” or “In one sentence, what can you do on this computer?” Do not open with a task that touches your files. You are testing the connection, not commissioning work.
Where
In your terminal, in the same environment where you installed and configured Hermes.
Expect to see
Hermes starts, then answers you in plain language. Whether you see a full-screen interface or a scrolling command-line session depends on which flag you used.§16
Structurally, both interfaces open the same way: a banner, then an input prompt waiting for your first message.§23
Watch for a real answer to your actual question, not a greeting. A banner proves it started. An answer proves the model is connected and reachable. Only the second one is what this section is for.
Save / apply
Nothing to save. Conversation is immediate and applies nothing to your system.
Exit when you are done: the slash command /quit (also aliased as /exit) ends the session cleanly, and Ctrl+D is the keybinding equivalent. /quit --delete also removes the session history. Closing the terminal window also ends the session, but the slash command is the clean exit.§24
Verify success
All three must be true:
- Hermes started without an error.
- You asked a question and got a relevant answer to that question, not just a startup banner.
- The answer arrived without a credentials error. could not resolve credentials from session means your provider configuration is wrong, not that the conversation failed.§19
Common friction
Security / privacy
What this step exposes
Everything you type goes to your model provider over the internet, along with whatever context Hermes includes. The habit starts here: assume anything you type reaches the provider.
This is also the first moment the agent can act rather than just answer. Keep the first conversation to questions, not tasks, until Section 5 is done. Approvals do have a working default (approvals.mode defaults to smart), so you are not unprotected; you just have not made any deliberate decisions about it yet.§7
Next safe step
Go to Section 5, Security baseline. It is the last section. Stopping here is tempting because it works, but you have a working agent with default permissions you have never looked at, and that is the one genuinely unfinished state in this path.
How do I know this worked?
- Hermes started and you saw an interface.§16
- You asked a question and received an answer that actually addressed it.
- No credentials error appeared.§19
- You can start Hermes again, from a new terminal, without looking anything up.
If any line is untrue, go back to Verify success and then Common friction above before continuing.
Not yet verified1 detail this guide will not guess at
- The exact banner text of the classic CLI and the TUI (it is skin-dependent, via the display.skin setting, so only the banner-then-prompt structure is asserted).
Security baseline
Goal
Hermes asks before it does anything consequential, your secrets file is not readable by anyone who wanders past your machine, and you know which protections do and do not apply on your platform. This is what turns a working install into one you can leave running.
Prerequisites
- Section 4 complete: Hermes runs and answers.
- Knowing where your config lives, from Section 2: %LOCALAPPDATA%\hermes\ on native Windows, ~/.hermes/ on macOS, Linux, and WSL2.§6
- Willingness to edit config.yaml. This is the one section where you open the settings file yourself.
Exact user action
There are four moves. Do all four.
1. Know your approvals defaults, and confirm them deliberately. The keys that decide what Hermes may do without asking, with their defaults: approvals.mode (smart | manual | off, default smart); approvals.timeout (seconds, default 300); approvals.cron_mode (deny | approve, default deny); approvals.single_query_mode (deny | approve, default deny); approvals.mcp_reload_confirm (default true); approvals.destructive_slash_confirm (default true); approvals.deny (your own rules, written as fnmatch glob patterns).§7
There is a third “no human present” gate as well: approvals.unattended_mode (deny | approve, default deny), which covers sessions triggered by webhook or API. The defaults are sensible. Keep all three unattended gates at deny unless you have a specific reason. The point is that you have now looked at them on purpose.§8
2. Know where your own deny rules go. approvals.deny takes fnmatch glob rules, and deny rules are evaluated before --yolo and before approvals.mode: off. They are the personal hard line: a future impatient version of you who disables approvals still cannot cross them. When you have a rule you trust, this is where it belongs; a worked example is listed under Not yet verified at the end of this section, so do not guess at the syntax. One hard limitation: deny rules apply only to host-reaching backends (local, SSH, and host-mounted Docker). An isolated container backend skips this layer entirely.§7
3. Know your network and supply-chain settings, and the one platform gap. security.allow_private_urls (default false); security.tirith_enabled (default true); security.tirith_path (default "tirith"); security.tirith_timeout (default 5 seconds); security.tirith_fail_open (default true); security.allow_lazy_installs (default true); security.acked_advisories; security.website_blocklist. For a stricter posture, flip security.tirith_fail_open to false: fail-open means that if the scanner cannot answer in time, the command proceeds anyway.§9
The platform gap, stated plainly: on native Windows, Tirith is silently skipped because it has no prebuilt binary there. The Tirith binary ships for Linux and macOS. The other keys still apply on native Windows, but command-content scanning does not, and you will not be warned. If this matters to you, WSL2 gets the protection back.§9
4. Know what HERMES_WRITE_SAFE_ROOT does and does not cover. It is an environment variable that restricts the write_file and patch tools to directory prefixes you specify. If you set it, include your Hermes folder itself (~/.hermes, or %LOCALAPPDATA%\hermes on native Windows) in the root list, or the agent’s own state writes (cron, skills) break. And it does not restrict the terminal tool, which runs as the host user, so it is not a sandbox against a hostile agent: container isolation is the real boundary. Treat it as a guardrail against accident, not a wall against intent.§10
Where
The settings file: config.yaml in your Hermes folder, ~/.hermes/config.yaml. It holds settings such as model, terminal, TTS, and compression. The secrets file: .env in the same folder, holding API keys, bot tokens, and passwords. Do not put settings there and do not put secrets in config.yaml.§6
The environment variable is set in your shell environment, not in config.yaml. Open config.yaml in any plain text editor. It is a normal file.
Expect to see
A YAML settings file with named sections. The approvals and security keys above are the ones you are looking for.§7, §9
A key you have never set may not appear in the file at all, and that is normal: it is running on its documented default. Do not panic at an absent key.
Save / apply
Save config.yaml in your editor. Safest habit, and the one this guide recommends: exit Hermes, make your edits, then start a new session.
If you choose to set the environment variable, apply it the way your platform applies environment variables persistently, so it survives a reboot (the exact per-platform steps are not yet verified here).
Then, if you know how on your platform, harden the folder permissions, wherever your path resolves: %LOCALAPPDATA%\hermes\ on native Windows, ~/.hermes/ everywhere else. The goal is simple: your user can read and write it, and no other account on the machine can read it at all. That folder holds your API keys.§6
Verify success
Each check has a stated pass condition:
Config is valid§11
hermes doctorPass condition: it does not report a configuration error introduced by your edits. A YAML typo is the most likely way to break this.
- Approvals actually gate. With approvals.mode at smart or manual, start a session and ask Hermes to do something real but harmless, such as creating a file in a scratch folder. Pass: it asks you before acting.§7
- Deny rules hold, if you have written any. Ask it to do something a rule forbids. Pass: it is blocked. This is the rule set that survives --yolo and approvals.mode: off, so confirm it rather than assume it. If you have not written a rule yet, skip this check.§7
- Secrets are not world-readable. If you know how to inspect file permissions on your platform, check the Hermes folder and the .env file. Pass: your user can read them, other accounts on the machine cannot. The exact commands are not yet verified here (see the panel below).
Common friction
Security / privacy
What this step exposes
The layers you now have, in order of how much they actually protect you: (1) approvals, including your own deny rules, evaluated before --yolo and before approvals.mode: off; (2) the three unattended gates, cron_mode, single_query_mode, and unattended_mode, all defaulting to deny; (3) network and supply-chain settings, with the native-Windows Tirith gap; (4) HERMES_WRITE_SAFE_ROOT, an accident guardrail and explicitly not a sandbox; (5) file permissions on your secrets, because everything above is irrelevant if someone can simply read your .env.§7, §8, §9, §10, §6
One thing to keep watching: if you ever arrange for Hermes to start automatically and stay running, you have adopted an unattended posture whether or not you intended to, and the approvals and deny rules stop being optional. On a real install, Hermes was found running as an always-on, auto-starting service, which is an unattended posture by definition. Nothing in this path sets that up; it becomes relevant under Go further or Advanced.§18
When you update: hermes update pulls the latest code and reinstalls dependencies, with --check to preview and --backup to snapshot first. Use both, then run hermes doctor. On a Docker install, hermes update is not available and you pull a new image instead.§12, §5
Next safe step
Nothing. You are done. You have reached WORKING HERMES. Stop, use it for a couple of weeks, and find out what you actually want before adding anything.
How do I know this worked?
- You have looked at your approvals keys deliberately and know what each default is.§7, §8
- All three unattended gates (cron_mode, single_query_mode, unattended_mode) are at deny.§7, §8
- You know that approvals.deny is where your own hard-line rules go, and that they hold even if approvals are later switched off.§7
- Hermes asked your permission before doing something on your machine, and you saw it happen.
- You know that .env holds your API key, where that folder is on your platform, and that only your user should be able to read it.§6
- You know whether Tirith runs on your platform, and that it is silently skipped on native Windows.§9
- You know HERMES_WRITE_SAFE_ROOT is a guardrail against accidents and not a sandbox against a hostile agent.§10
- hermes doctor runs clean after your edits.§11
If any line is untrue, go back to Verify success and then Common friction above before continuing.
Not yet verified5 details this guide will not guess at
- The exact YAML syntax and a worked example of an approvals.deny rule, including what a rule is matched against.
- The exact syntax for HERMES_WRITE_SAFE_ROOT with multiple directory prefixes, and how to set it persistently on each platform.
- Whether a fresh install writes every approvals and security key at its default into config.yaml, or only the keys you configured.
- Whether Hermes must be restarted for edited config.yaml values to take effect.
- The exact recommended permission values and commands for hardening the Hermes folder and .env on each platform.
Milestone
WORKING HERMES
If the checklists in all five sections are complete, you have a WORKING HERMES:
- Installed on a supported platform.§1
- Connected to a model that meets the 64,000-token minimum.§15
- Proven by a real conversation.
- Gated by approvals you chose on purpose, with deny rules that survive later carelessness.§7
- Storing its secrets somewhere you know, with permissions you have checked.§6
That is the finish line, not a checkpoint. Nothing on this page is provisional and nothing is waiting to be completed later. If you never open the next sections, you still have the thing this guide promised.
Keeping it working
- Update deliberately: hermes update --check previews, hermes update --backup snapshots first. Docker installs pull a new image instead.§12, §5
- Run hermes doctor right after every update, because new releases regularly change security defaults.§12, §11
Nothing here requires a purchase from us, and there is nothing to buy on this page. Hermes and your model provider have their own terms and their own bills. Read both.
Optional · after WORKING HERMES
Go further: what do you want Hermes to do next?
You do not need any of this. WORKING HERMES is a complete outcome, and everything here is an addition to something that already works. What these items share is reach: each gives Hermes a new way to be contacted, or a new place to act. That is the whole appeal and the whole risk in the same sentence, so each deserves its own decision.
Rules that apply to every item
Add one at a time, and live with it. Adding three at once means you cannot tell which one caused a surprise.
Re-read your security baseline after each addition. Anything that lets Hermes be triggered when you are not sitting there runs into the unattended gates you set: cron_mode, single_query_mode, and unattended_mode, all defaulting to deny.§7, §8
Talk to Hermes remotely
Real-world notesReach Hermes from your phone.
Talk to Hermes through a Telegram bot, so the agent is reachable when you are away from the terminal.§20
From a real setup session: a bot token was briefly pasted into a plain terminal before being entered correctly (nothing broke, but it was on screen); /sethome is a separate, easy-to-miss step after the first bot message, with TELEGRAM_HOME_CHANNEL as the documented recovery; and running a second, similarly configured agent alongside caused real confusion about which token belonged to which agent. Treat a bot token like a password, revoke and regenerate it in BotFather if ever exposed, and never reuse one token across two services running at the same time.
Work with websites
OutlineLet Hermes read and act on web pages, rather than only what you paste into it.
A browser connection.§13, §9
Not yet verified: whether Hermes ships a browser capability, what it is called, and how it is enabled. The setup wizard has a tools section and there is a security.website_blocklist setting, which suggest web-reaching behavior, but no browser tool or procedure is documented.
Work with Google Workspace
OutlineConnect calendar, mail, and documents so Hermes works with what is already in your Google account.
Google Workspace.
Not yet verified: whether Hermes supports Google Workspace integration, which services are covered, and the authorization and scope model. If you do connect Google, the MRE recommended setup is a dedicated Google identity granted only the permissions the agent requires (least privilege, smaller blast radius).
Give Hermes its own email or identity
OutlineA dedicated mailbox, separate from your personal inbox, so agent mail is contained and revocable.
Dedicated email or digital identity.
Not yet verified: whether Hermes supports an email channel, how a mailbox is connected, and which providers are supported.
Reach Hermes by voice, phone, or SMS
OutlineSpeak or text instead of typing, and have it speak back.
Voice output exists as a configured surface: the setup wizard includes a tts (text to speech) section.§13
Not yet verified: which TTS providers are supported and how they are configured; whether voice input, telephony, or SMS are supported at all.
Run AI locally
OutlineRun the model on your own hardware so your prompts and context never leave your machine.
This is the hardware question, and it belongs here rather than in the five sections above. Your operating system does not determine whether you can run a model locally, and local capability does not change your install path.§15, §14
The one constraint that carries over unchanged: any local model must still meet the 64,000-token minimum, because Hermes rejects smaller windows at startup regardless of where the model runs. Not yet verified: which local runtimes are supported, how they are selected, and the minimum hardware.
Each item becomes its own guide, with the same structure and the same closing question as the sections above. Items marked Outline carry no instructions yet, by design.
Optional · separate from Go further
Advanced: changing the terms Hermes runs under
Advanced is not a longer Go further, and the two are kept separate on purpose. Go further changes what Hermes can reach; Advanced changes the terms it operates under: where it is isolated, whether it runs when you are not there, and how many agents are involved. Finish the security baseline before anything here. Several items reduce or relocate protections you set there, and reducing a protection you never configured is not a decision, it is an accident.
The line that runs through everything here
An always-on, auto-starting gateway is an unattended posture by definition, and once that is true, approvals and deny rules are not optional. Most items here move you toward that posture. Know when you have crossed the line, because on a real install it was crossed without being noticed.§18
Container isolation for tool execution
OutlineRun the agent’s tools inside a container so its actions are bounded by the container rather than by your user account.
The terminal.backend: docker setting, which is not the Docker install path. Container isolation is described as the real boundary, but your approvals.deny rules apply only to host-reaching backends, so this strengthens one boundary and removes another.§5, §10, §7
Tightening the write boundary
OutlineUse HERMES_WRITE_SAFE_ROOT deliberately, with a correct root list.
~/.hermes must be in the root list or the agent’s own state writes break; the variable restricts write_file and patch only, never the terminal tool.§10
Unattended and scheduled operation
OutlineLet Hermes act on a schedule or in response to a trigger, with no human present.
Three separate gates, all defaulting to deny, and not interchangeable: approvals.cron_mode for scheduled runs, approvals.single_query_mode for one-shot queries, and approvals.unattended_mode for webhook and API-triggered sessions. approvals.timeout (default 300 seconds) means something different when nobody is there to answer.§7, §8
Running Hermes as an always-on service
OutlineHave Hermes start automatically and stay running.
On a real macOS install this was done with launchd (RunAtLoad and KeepAlive) and was still running months later. The gateway has its own management commands (hermes gateway setup, restart, status). This is where the unattended line gets crossed. Not yet verified: an officially documented service-installation procedure for any platform.§18, §20
A stricter supply-chain and network posture
OutlineMove from shipped defaults to a deliberately stricter configuration.
The lever most worth understanding is security.tirith_fail_open (default true; false is stricter). The native-Windows Tirith gap carries into every item here.§9
Multiple agents (Bot Mode)
OutlineRun more than one agent, communicating with each other and with users in group-chat-like environments.
Introduced in v0.21.0. The friction to lead with is not technical: separate tokens per agent, never one token reused across two services running concurrently. Not yet verified: how Bot Mode is enabled and how approvals apply across agents.§17, §20
Update discipline on a customized install
OutlineUpdate without silently losing a hardened configuration.
hermes update --check to preview, --backup to snapshot, then hermes doctor immediately, because new releases regularly change security defaults. Docker installs pull a new image instead.§12, §11, §5
Setup modes
OutlineChoose how much the wizard decides for you when reconfiguring.
Quick Setup (Nous Portal, also hermes setup --portal), Full Setup, and Blank Slate (everything off except provider and model, File Operations, and Terminal; re-enable with hermes tools). Blank Slate is a posture choice that interacts with isolation, unattended operation, and multi-agent.§27, §13
The order to take these in: Container isolation and the write boundary before unattended operation and the always-on service. Setting up an agent to run without you, and then deciding afterwards where it is allowed to act, is the wrong order, and it is the order most people take.
About this guide
This guide is based on the current Hermes Technical Truth Registry and is updated as Hermes evolves. Where a detail still needs verification, we say so clearly rather than presenting it as settled fact.