Hermes Agent Setup Guide: Zero to Running in 30 Minutes

Hermes Agent Setup Guide: Zero to Running in 30 Minutes

Hermes Agent is an open-source AI agent framework from Nous Research that runs in the terminal and can extend into messaging platforms, cron jobs, webhooks, and shared task workflows.

This guide is the path I would use if I had to set it up again on a clean machine. The goal is not to configure the whole system. The goal is to get from zero to a working Hermes session, then add the pieces that make it useful for real work: tools, skills, memory, gateway, and a first autonomous task.

If you only want a coding assistant, you can stop after the CLI works. If you want an agent system that keeps context and acts on a schedule, keep going. This is for builders, operators, and technical teams who want Hermes Agent installed first and refined second.

What you will have after 30 minutes

By the end, you should have the core CLI loop working. Gateway setup may take longer if platform credentials, bot tokens, or OAuth flows slow you down. The target state is:

• Hermes installed on Linux, macOS, or WSL
• one model provider configured
• the CLI running with terminal and file tools
• at least one reusable skill installed or created
• memory enabled for cross-session context
• an optional messaging gateway ready for Telegram or Discord
• a smoke test that proves the agent can read, write, run commands, and remember a small fact

That is enough to start building. Not enough to trust it with production automation yet. Trust comes after you add scopes, logging, review gates, and failure handling.

Prerequisites

You need bash or a POSIX-ish shell, Git, curl, and one model provider. I use OpenRouter and provider-specific keys depending on the task, but one provider is enough for the first run.

The setup assumes one of these environments:

• Linux
• macOS
• WSL on Windows

You also need an API key or OAuth login for at least one supported provider. Hermes supports OpenRouter, Anthropic, OpenAI, DeepSeek, Gemini, Nous Portal, GitHub Copilot, local OpenAI-compatible endpoints, and more. Pick one you already have access to. Model shopping is a distraction during setup.

Minute 0 to 5: install Hermes

Run the installer:

The official Hermes Agent installation guide is the source of truth if the command changes.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Restart your shell if the installer updates your PATH. Then verify the command exists:

hermes --version

If that prints a version, move on. If it does not, check whether the installer added a local bin directory to your shell profile. The fix is usually opening a new terminal or sourcing the file the installer modified.

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

Then run the health check:

hermes doctor

Before setup, provider and config warnings are expected. At this point you are checking that the command, Python environment, and core dependencies are present. A broken PATH or missing dependency costs more time later than it takes to check now.

Minute 5 to 10: run the setup wizard

Start with the wizard:

hermes setup

The official Hermes Agent quickstart is worth keeping open while you do this. I still prefer running the checks below because they prove the install in your shell, with your provider, under your profile.

The wizard walks through model, terminal, gateway, tools, voice, and agent settings. For a first setup, keep it boring:

• choose one provider
• set one default model
• keep the terminal backend local
• enable the file and terminal toolsets
• keep risky automation behind manual approval

You can change the model later:

hermes model

You can inspect config later:

hermes config
hermes config path
hermes config edit

Hermes stores normal settings in ~/.hermes/config.yaml and secrets in ~/.hermes/.env for the default profile. Named profiles live under ~/.hermes/profiles/<name>/. Keep that split. Config belongs in YAML. Keys belong in env.

My rule: get one model working before touching anything else. Multi-provider routing, credential pools, local inference, and gateway adapters are useful later. During first install they create more possible failure points.

Minute 10 to 13: start your first session

Launch the CLI:

hermes

Ask it something that needs no tools first:

Explain what tools you can use in this session in one paragraph.

Then test a single non-interactive query:

hermes chat -q "Say 'Hermes is installed' and nothing else."

The second command matters because it proves Hermes works outside the interactive interface. That mode is useful for scripts, cron jobs, and quick shell workflows.

Now test model switching with a model your configured provider supports:

hermes chat -m <provider>/<model> -q "Return the word ok."

For example, an OpenRouter-backed setup uses an OpenRouter model slug. An Anthropic-backed setup uses an Anthropic model name. The command format is the part to remember. Provider and model choices change. The workflow stays stable.

Minute 13 to 17: enable tools deliberately

Hermes is not useful because it can chat. It is useful because it can act on the machine.

List toolsets:

hermes tools list

For a first working agent, enable these:

• terminal
• file
• web, if you want research
• skills
• memory
• todo, if you want session planning

Use the interactive tool manager when you want to change them:

hermes tools

Tool changes apply on /reset or a new session. That is intentional. A running agent should not have its tool surface mutated halfway through a task. Prompt caching and tool expectations both get cleaner when a session's capabilities stay fixed.

Run a practical smoke test inside Hermes:

Create /tmp/hermes-smoke-test.txt with one sentence, read it back, then remove it.

Watch how the agent asks for command approval if your approval mode requires it. Keep approvals on while you are learning the system. The slight friction is good. It teaches you what the agent is trying to do.

Minute 17 to 20: add memory deliberately

A stateless agent is a demo. A useful agent remembers stable facts. Hermes has built-in profile memory, a memory toolset for explicit memory actions, and optional external memory provider plugins. Do not blur those together.

First, make sure the memory toolset is enabled if you want the agent to write and recall memories through tools:

hermes tools list
hermes tools

Use provider setup only when you want an external backend such as Honcho, Mem0, or another memory plugin:

hermes memory status
hermes memory setup

With the memory toolset enabled, test it in a low-stakes way:

Remember that my test project is called hermes-lab.

Start a new session:

hermes

Ask:

What is my test project called?

If it answers correctly, cross-session memory works. If it does not, check whether memory is disabled per profile or whether you are using a different profile than the one that stored the fact. After the test, ask Hermes to remove the hermes-lab memory if you do not want that temporary fact kept.

The same cleanup rule applies to the end-to-end smoke test later in the guide. Use memory to prove the system works, then remove test facts you do not want carried into real sessions.

Memory should hold stable preferences, environment facts, and durable conventions. It should not hold raw task progress. Task progress belongs in logs, issues, kanban cards, or project files. I wrote more about that split in AI Agent Memory: How I Built Persistent Memory Into My Agent Org.

Minute 20 to 23: use skills before you need them

Skills are one of Hermes' strongest design choices. A skill is a reusable procedure the agent can load into context when a task matches. It is not just a prompt snippet. It is operational memory.

List skills:

hermes skills list

Search the hub:

hermes skills search github

Install one if it fits your workflow:

hermes skills install github-pr-workflow

You can also load a skill explicitly when starting a session:

hermes -s github-pr-workflow

The real value appears after the first few corrections. When Hermes solves a messy task, ask it to save the workflow as a skill. Next time, the agent starts from the working procedure instead of rediscovering it.

This is how you keep the system from becoming one giant instruction file. Stable identity belongs in the profile. Reusable procedures belong in skills. Temporary task state belongs somewhere else.

Minute 23 to 26: create a profile boundary

Profiles are separate Hermes instances with their own config, sessions, skills, and memory. Use them when the role boundary matters.

Create a profile:

hermes profile create ops

Run Hermes under that profile:

hermes --profile ops

Show profile details:

hermes profile show ops

You do not need six profiles on day one. Start with one default profile. Add a second when the work changes enough that memory and voice should not mix.

This is the same reason I prefer specialist agents over one giant chat thread. Scope boundaries make context cleaner. I wrote the longer argument in Why Specialist Agents Beat One Big AI Chat.

Minute 26 to 28: wire the gateway if you want chat-based control

The gateway lets Hermes run through messaging platforms. Telegram and Discord are the obvious first choices, but the same gateway pattern supports Slack, Signal, Matrix, email, webhooks, and more.

Start the setup flow:

hermes gateway setup

Run the gateway in the foreground first:

hermes gateway run

Only install it as a service after the foreground run works:

hermes gateway install
hermes gateway start
hermes gateway status

Foreground first is my default rule for any daemon. You want to see the real error once before systemd or a background wrapper hides it.

Once the gateway works, keep the first permissions narrow. Do not give a phone chat full production access on the same day you install it. Start with read-only tasks, notes, and simple shell checks. Add write actions after you understand approval prompts and logs.

Before any customer-impacting or money-moving automation, add audit logs, scoped credentials, review gates, and a rollback path. A working install is not the same thing as a safe production agent.

Minute 28 to 30: run the end-to-end smoke test

Now run a test that crosses the main pieces:

Create a short note at ~/hermes-lab/notes/setup-smoke-test.md with today's date using the terminal/date command if needed, list the tools or toolsets available in this session, and remember that this setup smoke test passed as a temporary test fact.

Then start a fresh session and ask:

Did the setup smoke test pass? If yes, read the note path back to me.

After it passes, remove the temporary smoke-test memory unless you want it kept. A memory system that stores every test fact becomes noisy fast.

This proves four things:

1. the model responds
2. tools can touch the file system
3. memory survives a new session
4. Hermes can report what it did in plain language

That is the 30-minute finish line.

What I configure after the first run

The first 30 minutes are about a working loop. The next hour is about making it safe enough for daily use.

I usually configure these next:

• approval mode, so destructive shell commands do not run silently
• secret redaction, if tool output could expose keys
• session pruning, so old transcripts do not grow forever
• cron jobs for scheduled checks
• webhook subscriptions for event-driven work
• kanban if multiple profiles need durable task handoffs
• profile-specific skills for each role
• usage and cost monitoring, so provider spend does not become invisible. Add provider spend alerts or budget limits where the provider supports them

The kanban system is the piece that turns Hermes from a single assistant into an agent team. A task can be created, assigned, blocked, retried, completed, and handed off with structured metadata. That matters when work spans more than one model call or one agent role.

For solo use, kanban is optional. For a multi-agent operating system, it becomes the coordination layer.

Failure modes I would check first

If setup fails, debug in this order:

1. hermes doctor
2. hermes config check
3. hermes model
4. hermes tools list
5. hermes gateway status, if the failure is platform-related
6. grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -100, if the gateway starts but messages do not arrive

Most first-run failures are not deep. They are bad PATH state, missing API keys, wrong model names, disabled tools, or a gateway token pasted into the wrong field.

For Discord, check Message Content Intent in the bot settings. For Slack, check whether the bot is subscribed to channel message events. For WSL, check whether systemd is enabled before expecting a user service to survive a closed terminal.

Do not debug five layers at once. Prove the CLI. Then prove tools. Then prove memory. Then prove gateway.

The operating model matters more than the installer

Hermes is easy to install. The hard part is deciding what authority the agent gets.

My recommendation is conservative:

• start with local CLI use
• keep command approvals on
• give it file access in a sandbox first
• add memory after you understand what should be remembered
• add gateway after CLI behavior is predictable
• add cron and webhooks last

That order keeps the blast radius small while the agent earns trust.

A working agent setup is not a pile of features. It is a loop: context comes in, the agent acts, the action is logged, durable lessons become memory or skills, and the next session starts with less repeated explanation.

That loop is what makes Hermes worth setting up.

If you want this running as an agent team instead of a solo CLI, start with the specialist agent and memory guides below. The install is the easy part. The operating layer is where the value shows up.

If you want this running for a real team, Mimir Works can design the scoped workflows, logging, review gates, and handoffs that make a working Hermes install safe to use.

Read next: Why Specialist Agents Beat One Big AI Chat and AI Agent Memory: How I Built Persistent Memory Into My Agent Org.