Hermes Agent, set up safely

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

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: it decides whether Section 2 shows you a download button or a command. Docker is a supported path this page does not walk yet.

Fully supported, and Nous Research says it works to never break installs or updates for these: macOS on Apple Silicon, Windows 10 and 11, Linux, Windows through WSL2, and Docker.

Best-effort, where a new release may break things: Android through Termux, and Nix. Neither is a normal starting point.

Unsupported: Intel Macs, AUR, PyPI, and Homebrew.

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

Do not install via Homebrew, even if a brew formula appears to exist. It is listed as unsupported.

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.

Answer both, and be specific:

1. 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”).
2. State its tier: fully supported, best-effort, or unsupported.
3. 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.

• Section 1 complete: you know your platform and its tier.
• A working internet connection, since the installer downloads from the internet.
• macOS 12 or later on an Apple Silicon Mac. Intel Macs are unsupported (Section 1).
• 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.

Nothing to save by hand. The installer writes what it needs.

Hermes Desktop keeps its settings in the same files a terminal install uses, so anything you set in the app is what Sections 3 and 5 refer to.

Terminal route only: 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.

If you installed Hermes Desktop: open it. If it reaches the first-run setup or the chat window without an error, the install is proven. The terminal checks below are optional extra proof; you do not need them to continue.

hermes doctor

hermes doctor --fix

hermes --version

1. Hermes Desktop opens to its first-run setup or its chat window. That alone proves Hermes is installed, which is what this section was for.
2. Or, if you ran the optional terminal check: the command is found and produces output rather than “command not found.” That alone proves Hermes is installed and reachable.
3. Either way, a complaint about a missing or unconfigured model is expected right now, because you have not connected one yet. That is Section 3’s job.

• Section 2 complete: Hermes opens on your computer (or, on the terminal route, 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.
• A model large enough for Hermes: at least 64,000 tokens of context. Mainstream current models are comfortably above that, and Hermes refuses a model that is too small rather than failing later.
• 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.

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.

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.

In the app: send a message. If it answers instead of telling you no model is configured, this section worked. Section 4 makes that a proper test.

hermes doctor

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

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

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.

You asked a question in the app and got a real answer to it. That is the section.

1. Hermes started without an error.
2. You asked a question and got a relevant answer to that question, not just a startup banner.
3. The answer arrived without a credentials error. could not resolve credentials from session means your provider configuration is wrong, not that the conversation failed.

• 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.
• Willingness to open one settings file in a plain text editor. It is a normal text file, you are mostly reading it, and the section tells you exactly what to look for.

Four moves, and the first three are mostly reading. The plain-English decision comes first each time; the exact setting names follow it so you can find them in the file.

1. Decide, on purpose, that Hermes asks before it acts. Out of the box it does: it checks with you before consequential actions, and the three settings that cover work happening with nobody watching are all set to refuse. Leave them that way. The whole move is looking at them once so the behavior is yours rather than inherited. The setting names, so you can find them in the file: approvals.mode (smart, manual or off; smart by default); approvals.timeout (seconds, 300 by default); approvals.cron_mode and approvals.single_query_mode (both deny by default); approvals.mcp_reload_confirm and approvals.destructive_slash_confirm (both true); approvals.deny, which is where your own rules go.

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.

2. Know where your own hard limits would go, even if you write none today. approvals.deny is a list of things Hermes may never do, and it is the one control that still holds if a future, more impatient you switches approvals off entirely. That is what makes it worth knowing about now. We do not print an example rule because the exact syntax is on this page's not-yet-verified list and we will not guess at it. One real limit: these rules apply when Hermes acts on your own machine or over SSH, and an isolated container skips the layer entirely.

3. Know that a command scanner exists, and whether you get it. Hermes can check the content of commands before they run. It is on by default, and by default it lets a command through if the check cannot answer in time; setting security.tirith_fail_open to false reverses that if you want the stricter posture. The other settings in this family, for when you go looking: security.allow_private_urls (false by default); security.tirith_enabled (true); security.tirith_path and security.tirith_timeout; security.allow_lazy_installs (true); security.acked_advisories; security.website_blocklist.

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.

4. Know that there is a way to fence off where Hermes may write files, and what it does not cover. It is an optional setting called HERMES_WRITE_SAFE_ROOT, and most people setting up their first agent will not touch it. Two things matter if you ever do: include the Hermes folder itself in the list, or the agent breaks its own housekeeping; and understand that it does not restrict the terminal tool at all. It is a guardrail against accidents, not a wall against a hostile agent; real isolation is a container, which is an Advanced topic.

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.

Each check has a stated pass condition:

hermes doctor

1. 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.
2. 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.
3. 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).