How to Set Up Hermes Agent Without Turning Everything On at Once

Hermes Agent is most useful when you treat it like a working operator, not a magic chat box. It can run in a terminal, call tools, remember durable facts, load task-specific skills, and talk through messaging platforms. That power is also why the setup should be layered. If you turn on models, tools, memory, gateway, cron, and plugins in one pass, every failure starts looking like every other failure.

This guide gives you the safer path: install Hermes, choose one model provider, prove a plain CLI chat works, then add tools, memory, skills, and messaging only after the base is healthy. By the end, you should know what command proves each layer works and where to look when it does not.

What Hermes Agent is

Hermes Agent is an open-source AI agent framework from Nous Research. The public docs and GitHub repo describe a tool-calling agent that can run from the CLI, use a configurable set of tools, manage skills, persist memory, and connect to many messaging platforms through the gateway.

The important setup idea is simple: Hermes is not one feature. It is a stack.

Layer	What it does	Do this when
CLI/chat	Talks to your selected model	First
Provider/model	Chooses where inference comes from	First
Tools	Lets Hermes act on files, shell, web, browser, etc.	After chat works
Memory/skills	Gives it durable context and reusable procedures	After you trust the base setup
Gateway	Connects messaging platforms	After CLI works
Cron/plugins/MCP	Adds automation and extensions	Later

That order matters. A broken model setup can look like a gateway issue. A disabled toolset can look like a model problem. A bad custom endpoint can make the whole install feel broken even when the CLI is fine.

Command map: what each command is doing

The guide uses a small set of commands. Here is what each one is for before you start copying and pasting.

Command	Plain-English job	What success looks like	If it fails
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash	Downloads and runs the official Linux/macOS/WSL2/Termux installer. -f fails on HTTP errors, -sS stays quiet but still shows errors, and -L follows redirects.	Installer completes and tells you how to reload your shell or run hermes.	Check the install docs and rerun from a clean terminal; do not continue until hermes --version works.
iex (irm https://hermes-agent.nousresearch.com/install.ps1)	Native Windows PowerShell installer. irm downloads the script; iex executes it.	PowerShell finishes setup and the hermes command is available in a new terminal.	Open a new PowerShell window, check execution-policy/security prompts, and compare against the Windows install docs.
hermes --version	Proves the hermes command is on PATH and prints local install/version information.	You see a Hermes Agent version and install metadata.	Reload your shell, open a new terminal, or revisit the installer output.
hermes doctor	Runs Hermes’ health check for dependencies and configuration.	It completes without blocking errors.	Fix the reported dependency/config item before touching tools or gateway.
hermes model	Opens the interactive provider/model picker.	A provider and default model are selected.	Recheck credentials, provider name, model name, and whether you need a non-interactive config path.
hermes setup --portal	One-shot Nous Portal path: OAuth login + Nous provider/model selection in a single interactive flow.	A Nous-backed provider and default model are saved.	Re-run after confirming Portal account/subscription; use hermes model for non-Portal providers.
hermes setup --portal (also opts into Tool Gateway)	If you accept the Tool Gateway opt-in, it enables a curated set of network/media tools for Portal sessions.	hermes tools list shows the Tool Gateway toolsets enabled.	Decline if you only want raw chat; toggle individual toolsets later.
hermes chat -q "Reply with OK."	Sends one non-interactive prompt. This is the simplest provider smoke test.	The model replies with OK or a sensible equivalent.	The model/provider layer is still broken; do not debug gateway yet.
hermes tools	Opens the interactive tool configuration UI.	You can see and adjust tool availability by platform.	Use hermes tools list for a non-interactive view.
hermes tools list	Prints enabled/disabled toolsets.	The toolsets you expect are visible.	Enable the needed toolset or scope it for one run with --toolsets.
hermes tools enable <name> / hermes tools disable <name>	Turns toolsets on or off.	A later hermes tools list reflects the change.	Start a fresh session if the running chat does not see the change.
hermes chat -q "..." --toolsets terminal	Temporarily enables a toolset for one smoke test. Here, it checks terminal access.	Hermes can answer using that toolset, if configured and allowed.	Check hermes tools list and terminal backend setup.
hermes memory status / hermes memory setup	Shows or configures memory provider behavior.	Status reports the active memory setup.	Keep using built-in memory until an external provider is deliberately configured.
hermes skills browse/search/install/list/config	Finds, installs, lists, and configures reusable skill procedures.	You can see installed skills and add one intentionally.	Use hermes skills --help; do not assume a filesystem path.
hermes gateway setup	Configures messaging platforms such as Telegram/Discord/Slack.	Platform setup completes and credentials/allowlists are saved.	Fix platform token/allowlist issues here, not in the model layer.
hermes gateway run	Runs the gateway in the foreground for testing.	Logs show the gateway is running and platform adapters connect.	Keep it foreground until the platform works; then consider install/service mode.
hermes gateway status	Reports gateway state.	Shows the gateway/platform status you expect.	Re-run hermes gateway setup or inspect platform-specific logs.
hermes sessions list	Lists saved sessions so you can confirm previous chats are persisted.	Recent sessions appear in date order.	Confirm you are using the intended profile/Hermes home (hermes profile show); cross-profile sessions are separate.

The pattern is: install command → health check → model smoke test → tool smoke test → gateway only if needed. That order prevents you from debugging the wrong layer.

Before you start

You need four things:

1. A supported place to run Hermes. The official installation docs cover Linux, macOS, WSL2, Termux, and native Windows. Use the native Windows installer if you want a Windows-first setup; use WSL2 if you already prefer Linux tooling.
2. One model/provider path. Common paths include Nous Portal, OpenRouter, Anthropic, OpenAI/OpenAI Codex, Gemini, MiniMax, local OpenAI-compatible endpoints, and others listed in the provider docs. If you are unsure, the easiest entry points to evaluate first are Nous Portal if you already have a Nous account/subscription, or OpenRouter if you want one API key that can route to many models. Pick one first. You can change later.
3. A terminal you can restart. After install, you may need to reload your shell so the hermes command is on PATH.
4. A small definition of success. For the first run, success is not “gateway, memory, tools, and automation all work.” Success is: hermes chat -q "Reply with OK." returns a sensible model response.

If you are using Nous Portal, the current CLI help confirms a shortcut:

hermes setup --portal

The command description says it logs in through OAuth, picks a Nous model, sets Nous as the inference provider, and opts into the Tool Gateway. That makes it a strong first path for users already using a Nous subscription. If you are using a different provider, run the normal setup/model flow instead.

Install Hermes

On Linux, macOS, WSL2, or Termux, the public installer path is:

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

On native Windows, the official PowerShell installer path is:

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

The GitHub repo also exposes installer scripts directly under scripts/install.sh and scripts/install.ps1, which is useful as a second source when checking what the docs installer points to. Do not publish assumptions about the exact version, local install directory, or Python path from one machine. Those change by install method and update state. The public-safe instruction is: run the install command from the official docs, restart or reload your shell, then verify your own machine.

Run:

hermes --version
hermes doctor

hermes --version proves the command is reachable and tells you what is installed on your machine. It may print a version, install method, Python version, and local install path. Those details are useful for troubleshooting but should not be copied into a public guide as universal facts.

hermes doctor is the next layer. It checks whether the local install and configuration are healthy enough to run. Treat it like a preflight check: if doctor reports a missing dependency or broken config, fix that first. Do not configure tools, gateway, or automation until the basic CLI is healthy.

Choose a model/provider

For a normal setup, use:

hermes model

The live CLI help describes this as the interactive provider and model picker. Use it to choose your provider, enter credentials, and select a default model. If you need non-interactive setup for a script or CI environment, use hermes config set ... with the current configuration docs instead of the interactive picker. If you are on Nous Portal, use hermes setup --portal when you want the one-shot route.

If you are using a local or custom OpenAI-compatible endpoint, verify the endpoint outside Hermes first. A wrong base URL or model name can make Hermes look broken while the real problem is the model server. Keep the custom path boring: one endpoint, one model name, one short test.

Before pointing Hermes at a custom endpoint, ping the model list yourself:

curl -s http://localhost:11434/v1/models | head -40

Or for a hosted OpenAI-compatible API:

curl -s -H "Authorization: Bearer ***" https://api.example.com/v1/models | head -40

If the model you plan to use is not listed, fix the endpoint first. Then run hermes model.

After model setup, run:

hermes chat -q "Reply with OK."

If that works, the provider layer is alive: Hermes can reach the selected model and get a response without needing tools. If it fails, re-run hermes model, check the provider credentials, or verify a custom endpoint outside Hermes. Do not troubleshoot the gateway yet. The gateway cannot fix a broken provider setup.

Enable only the tools you need

Hermes organizes capabilities into toolsets. Current CLI help confirms:

hermes tools
hermes tools list
hermes tools enable <name>
hermes tools disable <name>

Use the interactive hermes tools screen when you are not sure. Use hermes tools list when you need evidence of what is enabled.

A sensible starting point:

Need	Toolsets to consider	Verification
Coding or site work	file, terminal	Ask Hermes to inspect a harmless local file or current directory
Research	web/search	Ask it to summarize a known public page
Reusable procedures	skills	Ask it to list or load a relevant skill
Cross-session context	memory/session search	Check memory status and use it deliberately
Browser tasks	browser/computer-use	Add only for tasks that truly need browser automation
Scheduled work	cronjob	Add only after the manual process is proven

Tool-dependent claims must stay conditional. “Hermes can inspect files” really means “Hermes can inspect files when the file toolset is enabled and allowed in that platform.” “Hermes can run shell commands” means “when the terminal toolset is enabled and the backend is configured.” That conditional phrasing prevents bad guides and bad expectations.

For one-off tests, you can scope tools to a single run:

hermes chat -q "What is in this directory?" --toolsets terminal
hermes chat -q "Summarize https://example.com" --toolsets web

Only keep a tool enabled by default after it proves useful. The --toolsets flag is especially useful while testing because it changes one invocation instead of changing your platform-wide defaults.

Memory and skills: do not mix them up

Memory and skills solve different problems.

Memory is for durable facts the agent should remember across sessions: user preferences, stable environment details, and high-signal lessons. Current CLI help says Hermes has built-in memory and can also configure one external memory provider through hermes memory setup/status/off/reset. Because memory storage can vary by install, profile, and provider, avoid public claims like “all memory is always in this exact file path.” A safer instruction is:

hermes memory status
hermes memory setup

Use the memory feature deliberately. A simple rule:

Do save to memory:

• Stable user preferences and durable environment details.
• High-signal lessons learned that apply across sessions.

Do not save to memory:

• Temporary task progress or in-flight TODOs.
• One-off article drafts, commit messages, or session-specific notes.
• Stale operational history (an old VPS hostname, a one-time cron ID, yesterday’s deploy path).
• Things that already live in a skill, a source file, or session history.

Items in the “do not save” list belong in files, source notes, or session history, not in the memory store. Memory that fills with stale operational notes is the most common reason a Hermes setup slowly stops feeling useful.

Skills are reusable procedures. Current CLI help confirms commands such as:

hermes skills browse
hermes skills search <query>
hermes skills install <id>
hermes skills list
hermes skills config

Those are the skills commands you are most likely to touch first, not the complete skill-management surface. Use skills for repeatable workflows: “how to publish an ABS guide,” “how to troubleshoot a Cloudflare tunnel,” “how to run a code review.” A good rule: memory is for facts; skills are for procedures.

Add messaging only after CLI works

The messaging gateway is a separate layer. The live help describes:

hermes gateway setup
hermes gateway run
hermes gateway install
hermes gateway start
hermes gateway status
hermes gateway list

Use hermes gateway setup to configure platforms. Use hermes gateway run in the foreground when you are testing, especially in WSL, Docker, or Termux. Use the service/install path only after you know the platform connection works, and treat the exact service mechanism as platform-dependent. Check hermes gateway install --help or the current gateway docs before making it persistent.

The gateway can make Hermes feel like a personal bot, but it also adds platform tokens, allowlists, background processes, and logs. If the CLI chat is broken, the gateway will only hide the real problem. The right order is always:

1. hermes chat -q "Reply with OK."
2. hermes tools list
3. one safe tool test if needed
4. hermes gateway setup
5. hermes gateway status

For remote desktop or “same Hermes from another client” setups, follow the official dashboard/serve architecture rather than assuming an SSH terminal backend shares all state. Remote shell execution and shared Hermes state are different problems.

Verification checklist

Run these in order. Each step proves one layer.

Step	Command	What it proves
1	hermes --version	The command exists and prints install/version info
2	hermes doctor	Dependencies/config are not obviously broken
3	hermes model	Provider/model selection is configured
4	hermes chat -q "Reply with OK."	Model auth and basic chat work
5	hermes tools list	Tool availability is visible

A note on cost

Paid providers charge per token. A multi-provider setup, gateway attached to several platforms, and a busy cron can compound quickly. Two habits help:

• Keep the main model path boring until it is stable.
• Use hermes insights to review actual usage before assuming where the spend is coming from.

Sources used for this guide

These are the sources used to build and fact-check this guide. They are listed here because the setup steps can drift, and readers should be able to check the current docs before copying commands.

If an individual docs page does not load in an in-app browser, use the official docs home or text mirrors instead: Hermes docs home, short LLM docs text, or full LLM docs text. Those text versions are useful fallbacks because they avoid the heavier docs-site JavaScript.

Official Hermes docs

• Hermes Agent installation docs — install commands and supported platforms.
• Hermes Agent quickstart docs — first-run flow and basic setup expectations.
• Hermes CLI commands reference — command names, flags, and one-shot/setup/gateway behavior.
• Hermes configuration docs — config-file and non-interactive setup guidance.
• Hermes providers docs — supported provider/model paths.
• Hermes tools docs — toolset behavior and tool enablement.
• Hermes skills docs — skills concept and skills commands.
• Hermes memory docs — memory behavior and provider setup.
• Hermes messaging docs — gateway/platform setup.

Source repo and installer checks

• NousResearch/hermes-agent GitHub repo — public source repo and README-level project framing.
• Linux/macOS installer script — second source for the shell installer path.
• Windows installer script — second source for the PowerShell installer path.

Accuracy note

This guide was written by Hermes (MiniMax M3) and fact-checked against the official Hermes docs, the GitHub README, the installer scripts, and live CLI help from a working Hermes install on July 10, 2026. The article intentionally avoids exact local version numbers, private install paths, and one-machine memory file assumptions. The full source-notes audit and editorial review is at the Source notes page.

A few claims remain conditional by design: provider availability changes, toolsets only work when enabled, gateway status depends on the configured platform, and custom endpoints depend on real OpenAI-compatible behavior. For publication, keep those conditionals. They are not hedges; they are the difference between a safe setup guide and a brittle one.

See also

• Source notes for this guide — claim audit, sources, and the full revision log across the original draft, the MiniMax M3 comparison draft, and V2.