How to set up Hermes Agent (Nous Research)

Last checked Oct 22, 2026. Steps below follow the official Hermes Agent docs and README as of that date. Check the linked pages before you run anything, since commands change between releases.

What Hermes Agent is

Hermes Agent is an open-source personal AI agent built by Nous Research. It is released under the MIT license (README). The software is free. Model providers and optional hosted services have their own pricing (official site).

You can bring your own model provider. You can also use Nous Portal, which has a free tier and paid tiers: Plus at $20 per month, Super at $100 per month and Ultra at $200 per month, each with monthly credits (official site). Current plans and billing live in Nous Portal.

Before you start: security

Read the security docs before you give the agent access to your machine or your chats.

• Per SECURITY.md, the only security boundary against an adversarial model is the operating system. The approval gate, redaction and pattern scanners are not containment (SECURITY.md).
• The default local terminal backend runs commands on your host with no isolation (Security docs).
• Hermes checks commands against a list of dangerous patterns and asks you to approve matches (Security docs).
• For a messaging gateway, the docs’ checklist says: set explicit allowlists, never use GATEWAY_ALLOW_ALL_USERS=true in production, use a container backend, keep API keys in ~/.hermes/.env with tight permissions, use DM pairing, never run the gateway as root, and run hermes update regularly (Security docs).
• Report vulnerabilities privately via GitHub Security Advisories or [email protected]. There is no bug bounty (SECURITY.md).

Requirements

• Hermes Desktop runs on macOS 12+ and Windows 10/11. Linux uses the terminal install (official site).
• The macOS installer is Apple Silicon only. Intel Macs are not a supported platform (Installation docs).
• The POSIX source script needs Git, curl, tar and SHA-256 utilities. Windows can fetch its own pinned Git if Git is missing (Installation docs).
• Current first-party installs run on Python 3.14, which the installer manages for you (Installation docs).
• You need at least one model provider (Providers docs).

Install

Option 1: Desktop app

Download Hermes Desktop for macOS or Windows from the official site. On macOS, open the DMG and copy Hermes.app to Applications. On Windows, the App Installer installs the signed MSIX bundle (Installation docs).

Option 2: Terminal (Linux, macOS, WSL2)

Run the one-liner from the README:

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

Then reload your shell and start Hermes (README):

source ~/.bashrc    # reload shell (or: source ~/.zshrc)
hermes              # start chatting!

Option 3: Windows, native PowerShell

Run this in PowerShell (README):

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

Native Windows installs live under %LOCALAPPDATA%\hermes (README). If antivirus flags uv.exe in that folder, the README calls it a false positive and gives steps to verify the file.

Other methods

The docs also list a Termux APT package for aarch64 Android, a Docker image and a Nix setup (Installation docs). After a terminal-only install, hermes desktop builds and launches the desktop app (Installation docs).

Connect a model provider

Pick a provider and model with (Providers docs):

hermes model

Supported options include Nous Portal, OpenRouter, OpenAI, Anthropic, GitHub Copilot, local servers like Ollama and vLLM, and others (Providers docs). To set everything at once, run hermes setup (README).

If you use Nous Portal, one command logs you in via OAuth, sets Nous as your provider and turns on its Tool Gateway (README):

hermes setup --portal

If you see “API key not set”, the docs say to run hermes model or hermes config set OPENROUTER_API_KEY your_key (Installation docs).

Connect messaging apps

The gateway is one background process. It connects to Telegram, Discord, Slack, WhatsApp, Signal, Email and many other platforms. It also runs your cron jobs (Messaging docs).

Configure platforms with the interactive wizard (Messaging docs):

hermes gateway setup        # Interactive setup for all messaging platforms

Run it in the foreground with hermes gateway, or install it as a service (Messaging docs):

hermes gateway install # Install as a user service (Linux) / launchd service (macOS)
hermes gateway start # Start the default service
hermes gateway status # Check default service status

Limit who can talk to the agent with allowlists or DM pairing. hermes pairing approves or revokes pairing codes (CLI reference).

Scheduling

Hermes has a built-in cron scheduler that can deliver results to any platform (README). In chat (Cron docs):

/cron add "every 2h" "Check server status"

From the CLI (Cron docs):

hermes cron create "every 2h" "Check server status"

Scheduled jobs need the gateway running, since the gateway runs cron jobs (Messaging docs). Tasks that need an active agent do not run while it is stopped (official site).

Sandbox backends

The terminal backend decides where shell commands run. Built-in backends are local, Docker, SSH, Modal, Daytona and Vercel Sandbox. Singularity/Apptainer is a plugin backend (README).

Per the Security docs:

• local: no isolation, runs on the host. Dangerous-command check is on. Meant for development and trusted users.
• ssh: runs on a remote machine. Dangerous-command check is on.
• docker: container isolation. The docs suggest it for a production gateway.
• singularity (plugin): container, for HPC environments.
• modal: cloud sandbox.
• daytona and vercel_sandbox: cloud sandboxes.

On container and cloud backends the dangerous-command check is skipped, because the container is the boundary (Security docs). To use Docker, set terminal.backend: docker in config.yaml (Security docs).

Two cautions from the docs. Variables you add to terminal.docker_forward_env are readable by code in the container (Security docs). A terminal backend does not confine what runs in the agent’s own Python process, such as the code-execution tool, MCP subprocesses, plugins and skills (SECURITY.md).

Data directory and backups

Default data locations (Installation docs):

• Linux, macOS, WSL2 source install: ~/.hermes/
• Windows source install: %LOCALAPPDATA%\hermes\
• Docker: the mounted /opt/data/

Logs go to ~/.hermes/logs/ (Security docs).

hermes backup creates a zip of your configuration, skills, sessions and data. The default output is ~/hermes-backup-<timestamp>.zip. hermes import restores a backup (CLI reference). A profile export excludes credentials, so it is not a full backup (Installation docs).

Stopping and updating

Stop the gateway service with (Messaging docs):

hermes gateway stop # Stop the default service

Stopping a local agent ends its process but keeps its conversations, memories and skills (official site).

How you update depends on how you installed (Updating docs):

• Source install: hermes update. It moves from one stable release to the next.
• macOS app: the Update control in the desktop app.
• Windows MSIX: the Update control and Windows App Installer. Microsoft Store builds update through the Store.
• Docker: pull the image and recreate the container with the same data mount.
• Termux: pkg update, then pkg upgrade hermes-agent.

If something breaks, hermes doctor diagnoses issues (README).

Migrating from OpenClaw

Hermes can import OpenClaw settings, memories, skills and API keys. The hermes setup wizard detects ~/.openclaw and offers to migrate first (README). You can also run it any time (README):

hermes claw migrate              # Interactive migration (full preset)
hermes claw migrate --dry-run    # Preview what would be migrated
hermes claw migrate --preset user-data   # Migrate without secrets
hermes claw migrate --overwrite  # Overwrite existing conflicts

Per the README, imports cover SOUL.md, memories, user-created skills, the command allowlist, messaging settings, allowlisted API keys, TTS assets and, with --workspace-target, AGENTS.md (README). Run the dry run first so you can see what will move.