Getting started

Hermes Agent is an open-source AI agent built by Nous Research. You can chat with it in a terminal, a desktop app, or through messaging apps like Telegram and Discord, and it can run commands, edit files, browse the web and use other tools on your behalf.

Its main selling point is a learning loop: it keeps curated memory about you and your setup, saves reusable procedures as skills, and can search its own past conversations.

Yes. The software itself is free and open source under the MIT license. What you pay for is the AI model behind it: usage fees from whichever provider you connect, such as OpenRouter or OpenAI, or a Nous Portal plan if you choose that route.

For free models, Nous Portal has a $0 Free plan. Sign in with hermes model (pick Nous Portal) or hermes setup --portal, choose the Free plan in the browser, then pick a model marked as free tier, such as a variant with a :free tag. A fresh Hermes Desktop install can also start you on a free tier before you sign in, and hermes auth upgrade in a terminal (or /login in a chat) signs you in later.

If you run a local model on your own hardware, there are no model fees at all. The free tier is rate-limited, so heavy agent use usually needs a paid plan or your own provider key.

The docs list macOS on Apple Silicon, Windows 10 and 11 (native, no WSL required), Linux, WSL2 and Docker as top-priority (Tier 1) platforms. Nix and Android via Termux (aarch64 only) are best-effort Tier 2. The Windows MSIX desktop package needs Windows 11 22H2 or later; the PowerShell installer covers Windows 10.

Intel Macs: stable releases build the desktop bundle for Apple Silicon only, so on an Intel Mac install the CLI with the regular installer and run hermes desktop. 32-bit Macs are unsupported.

Docker hosts such as a NAS or unRAID box can run the official nousresearch/hermes-agent image with a data folder mounted at /opt/data; update by pulling a new image. Installing through pip/PyPI, Homebrew or the AUR is not supported.

On Linux, macOS or WSL2, run: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. On native Windows, run iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell. Desktop app packages are also available for macOS and Windows.

Afterwards reload your shell (for example source ~/.bashrc) and type hermes to start chatting. Don't run the installer with sudo; it installs into your user account.

For a normal installer-based (source) install, run hermes update. It moves you to the latest published stable release, refreshes dependencies, syncs bundled skills to every profile and restarts running gateways. hermes update --check previews first, and you can also send /update from a connected messaging app.

Hermes Desktop checks for updates in the background and offers a one-click update (About > Update now, or Update Hermes in the command palette). The app and the backend it talks to update separately; when you're connected to remote gateways, that button updates the backends first and the app last.

Other install types update their own way: Docker users pull a new image and recreate the container, Termux uses pkg upgrade hermes-agent, and Microsoft Store installs update through the Store. Check your version with hermes --version.

Run hermes uninstall. For source installs, preview what it will do first with hermes uninstall --dry-run. By default it can keep your configuration and data; --full also removes data, and --data removes user data only. Make a backup first, since these are destructive.

Desktop and package installs are removed with their own tools, for example Windows Settings for the MSIX/Store app or moving the macOS app to Trash.

Yes. hermes setup detects ~/.openclaw and offers to migrate, or you can run hermes claw migrate anytime. Add --dry-run to preview, or --preset user-data to skip infrastructure config (no preset imports secrets without --migrate-secrets).

It can bring over your SOUL.md persona, MEMORY.md and USER.md entries, user-created skills (into ~/.hermes/skills/openclaw-imports/), command allowlist, messaging settings, allowlisted API keys and, with --workspace-target, AGENTS.md.

Start with hermes import-agent. It auto-detects ~/.claude or ~/.codex, or you can name one: hermes import-agent claude-code or hermes import-agent codex. It shows a plan before writing anything, and --dry-run never touches disk.

For Claude Code it maps global CLAUDE.md into memory, Bash permission rules into command_allowlist and approvals.deny, MCP servers into mcp_servers, and skills into ~/.hermes/skills/claude-code-imports/. Your project instruction files keep working too, because Hermes reads CLAUDE.md and AGENTS.md as context files.

You don't have to choose one or the other. Hermes ships claude-code and codex skills that let it hand coding work to those CLIs, and hermes acp puts Hermes inside editors such as VS Code and Zed.

There is an official Termux package for 64-bit ARM (aarch64) Android devices. You add a signed APT repository, install it with pkg install hermes-agent, then run hermes setup. The package bundles Python, Node.js, ffmpeg and the other runtime pieces, so nothing has to compile on the phone. Don't use the desktop install.sh there.

Check the Termux page before you start: at the time of writing it carries a warning that the Termux package is currently broken and a fix is in progress.

Either works. Native Windows needs no WSL, Cygwin or Docker: the PowerShell installer puts Hermes in %LOCALAPPDATA%\hermes without admin rights, and the CLI, TUI, messaging gateway, cron, browser tool, MCP servers and web dashboard all run natively. hermes gateway install registers a Scheduled Task so the gateway starts at login.

WSL2 suits people who want a POSIX environment, for example fork semantics or Linux-style file watchers. The two installs coexist, because WSL keeps its data in ~/.hermes.

If you don't want a terminal, install Hermes Desktop: first-run onboarding gets you to a first message quickly, and you can connect Nous Portal (one sign-in for models plus web search, images, voice and a browser) or pick a provider later. If you like terminals, run the installer, then hermes setup.

Then follow the official Learning Path page, which has reading orders by level (beginner, intermediate, advanced) and by goal: coding assistant, Telegram or Discord bot, automation, a team of bots, or building your own skills. Beginners need about an hour: install, quickstart, CLI basics and configuration.

For help, the official channels are the docs (including the FAQ & Troubleshooting page), GitHub issues and the Nous Research Discord.

They are all front ends to the same agent, with the same config, keys, memory, skills and session history, so you can start a session in one and resume it in another. Pick by situation.

Hermes Desktop (hermes desktop) is the most complete: multiple chat tabs and windows, file browser and previews, Git review and worktrees, Bot Mode, voice, scheduled jobs and settings without YAML. The CLI (hermes) and TUI (hermes --tui) suit terminal users and servers. The web dashboard (hermes dashboard) is a browser admin panel for config, keys, sessions, logs, cron and skills.

Messaging apps through the gateway (Telegram, Discord, Slack and many more) are how you reach Hermes from your phone and run it around the clock. A few commands are surface-specific; for example /handoff and /browser connect are CLI-only, while /sethome and /restart are messaging-only.

Yes. Settings > Appearance has theme presets plus a live VS Code Marketplace search that converts any color theme into a Desktop theme, a Chat Font (desktop.font_family, including readability fonts like OpenDyslexic once installed) and a Terminal Font for the embedded terminal. Most bindings can be remapped in Settings > Keyboard Shortcuts.

For layout, the layout editor (titlebar button or Cmd/Ctrl+Shift+\) offers Simple (chat-first) and Advanced modes and saved layouts, and Hide keeps panes like the in-app Browser or Terminal running while collapsed. The in-app browser has a comment mode for annotating live pages.

The app's interface language can be switched in-app, and language packs can add or override UI languages. That only changes interface text; to have the agent answer in another language, just ask it to. Desktop plugins can add your own panes, pages and commands.

Start with something that recurs and that you'd otherwise do by hand, because that's where memory, skills and scheduling pay off. Good first projects: a morning briefing delivered to your phone (/blueprint morning-brief), a news or paper digest, research fanned out to subagents, turning notes into a weekly plan, or an inbox and calendar helper through the Google Workspace skill.

The docs' Automation Blueprints and Guides sections have ready recipes, from a daily briefing bot to GitHub PR review, uptime checks and revenue summaries. On a computer, it's also a full coding and file assistant in your terminal or Desktop.

Tell it about yourself and your setup early, so it can write useful memory, and correct it when it gets something wrong; that's how it improves.

In a terminal, hermes model is the full picker: add providers, sign in or enter keys, and set your default model. Inside a chat, /model switches between providers you've already set up, for example /model provider:model; add --global to keep it beyond the current session.

In Hermes Desktop the model picker sits in the composer, left of the microphone. A pick there applies to the current chat and follows you to new chats on that device, but doesn't change your saved default; set that in Settings > Model > Main model and click Apply. Each profile has its own default.

Switching mid-conversation makes the next message re-read the whole conversation at full price, so on long chats a fresh session on the new model is often cheaper.

Largely, yes. Describe what you want in chat and it can create scheduled jobs, install and write skills, and walk you through connections such as Google Workspace, whose setup is agent-driven. The bundled hermes-agent skill teaches it how Hermes itself is configured and extended.

Some steps still need you: signing in to providers (hermes model or Desktop's Providers page), creating bot tokens with services like Telegram's @BotFather, approving risky commands, and confirming blueprint jobs before they're scheduled. Those are deliberate checkpoints.

After it changes something, confirm it worked: hermes cron list for jobs, hermes skills list for skills, hermes doctor for overall health.

If it's published as a profile distribution (a git repository), install it with hermes profile install github.com/<owner>/<repo> --alias. It brings the author's SOUL.md, config, skills, cron jobs and MCP connections; your own credentials, memories and sessions stay on your machine. hermes profile update <name> pulls the author's next version and keeps your data, and hermes profile info <name> shows its manifest.

If someone sends you a single .tar.gz export instead, run hermes profile import <file> --name <name>, or /import in chat, or Import profile… in Desktop. API keys are stripped from exports, so sign in again.

Read what you're installing first. A profile can schedule jobs and enable tools, so treat one from a stranger like any other third-party code.

It's a capable coding agent: it reads, edits and runs code in your projects, follows AGENTS.md or CLAUDE.md, gets real type errors from bundled language servers after each edit, can work in isolated git worktrees, and has /review to send a second agent over your diff or PR. Desktop adds a Git review pane with commit, push and PR actions.

Claude Code and Codex are coding-focused agents from Anthropic and OpenAI, built around their own models. Hermes is a general-purpose personal agent that works with any provider, and adds memory across sessions, scheduled jobs and messaging-app access. How well it codes depends heavily on the model you pick.

You don't have to choose. Hermes ships claude-code and codex skills to delegate work to those CLIs, hermes import-agent brings over an existing Claude Code or Codex setup, and hermes acp runs Hermes inside editors like VS Code and Zed.

The differences are mostly about where it runs and who controls it. Hermes is open source (MIT) and runs on your own machine, a server or a hosted instance, so it can stay on around the clock, run scheduled jobs while you're away, and answer you on Telegram, Discord, Slack and other apps.

It works with almost any model provider or a local model, and keeps its own memory, skills and searchable session history on disk you control. You can switch models without losing that.

The trade-off is that you run and configure it. Hosted assistants such as ChatGPT handle that for you, and dedicated coding agents like Claude Code and Codex are tuned for their makers' models. Many people use Hermes alongside them; it can even delegate coding to the Claude Code and Codex CLIs.