Skip to content
Get packs

Guide · Open source

How to use Hermes Agent: install, run and schedule tasks

Updated · written with AI from the project's own documentation and checked against our catalogue data

Hermes Agent is an open-source AI assistant from Nous Research that you run on your own machine or server. This guide shows you how to install it, start a chat in the terminal, pick a model provider, connect a chat app and set up scheduled tasks. By the end you will have a working agent and know which commands to use next.

Hermes AgentNousResearch/hermes-agent · ★ 260k · MIT

Quick start

  1. 1Run the installer. Use the curl command on Linux, macOS or WSL2, or the PowerShell command on native Windows. Wait for it to finish.
  2. 2Reload your shell. Run source ~/.bashrc or source ~/.zshrc so the hermes command is available.
  3. 3Start the CLI. Type hermes to open the interactive chat.
  4. 4Pick a model provider. Run hermes model and choose a provider and model you have access to.
  5. 5Enable tools. Run hermes tools to choose which tools the agent can use.
  6. 6Connect a chat app. Follow the platform setup in the docs, then run hermes gateway.
  7. 7Check your setup. Run hermes doctor if something does not work.

Install Hermes Agent on Linux, macOS, WSL2 or Windows

On Linux, macOS, or WSL2, run the one-line installer from a terminal. After it finishes, reload your shell so the hermes command is available.

On native Windows, open PowerShell and run the Windows installer. The source says the installer sets up Python 3.14, Node.js, npm, ripgrep, FFmpeg and Python dependencies for you. Native Windows installs live under %LOCALAPPDATA%\hermes, while WSL2 installs live under ~/.hermes.

  • Linux, macOS or WSL2: use the curl command below.
  • Native Windows: use the PowerShell command below.
  • Android with Termux uses a separate guide, not the desktop installer.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Start your first chat with the hermes command

Once installed, type hermes in your terminal to open the interactive CLI. The README describes a full terminal interface with multiline editing, slash-command autocomplete, conversation history and streaming tool output.

If you want a guided setup that configures everything at once, run hermes setup.

  • hermes: start a conversation in the interactive CLI.
  • hermes setup: run the full setup wizard.
  • hermes doctor: diagnose any issues.
source ~/.bashrc # or: source ~/.zshrc hermes

Choose a model provider and switch between them

Hermes works with many model providers, including Nous Portal, OpenRouter, OpenAI and your own endpoint. Run hermes model to choose a provider and model. The README says you switch models with a command and no code changes are needed.

Inside a chat, the README mentions the /model command for picking a model by name. The README also describes a Nous Portal option that bundles model access with web search, image generation, text-to-speech and a cloud browser under one subscription. This is optional and you can use other providers.

  • hermes model: choose your LLM provider and model.
  • /model <name>: pick a model from inside a session (Nous Portal example).
  • hermes tools: configure which tools are enabled.
  • hermes config set and hermes config get: set or read individual config values.

Connect Hermes to Telegram, Discord, Slack or WhatsApp

The messaging gateway lets you reach the same agent from chat apps. The README lists Telegram, Discord, Slack, WhatsApp, Signal and CLI, all run from a single gateway process.

Start the gateway with the command below. Platform-specific setup, such as creating a bot token, is covered in the full documentation linked from the README, so follow those steps for each app.

  • Telegram, Discord, Slack, WhatsApp and Signal are listed as supported platforms.
  • Voice memo transcription is mentioned in the README.
hermes gateway

Set up scheduled, unattended tasks

The README describes a built-in cron scheduler that can deliver results to any connected platform. You describe the task in natural language, and the agent runs it unattended. The README gives examples such as daily reports, nightly backups and weekly audits.

Because scheduled tasks run without you present, check the results the first few times and confirm the agent has the tools and access it needs.

  • Examples from the README: daily reports, nightly backups, weekly audits.
  • Delivery can go to any connected chat platform.

Understand memory, skills and where the agent runs

The README says Hermes stores agent-curated memory, searches past conversations with FTS5 session search, and creates reusable skills from complex tasks, improving them during use. Skills are described as compatible with the agentskills.io open standard.

For running location, the README lists six terminal backends: local, Docker, SSH, Modal, Daytona and Vercel Sandbox, plus plugin backends such as Singularity/Apptainer. Choose a backend based on where you want commands to execute and what data may leave your machine.

  • Local, Docker, SSH, Modal, Daytona and Vercel Sandbox are listed terminal backends.
  • Daytona and Modal are described as offering serverless persistence.

What people use it for

  • A developer hosting a personal agent on a small VPS or home server.
  • Reaching one assistant from Telegram on a phone and from the terminal on a laptop.
  • Running a nightly backup or a weekly audit described in plain language.
  • Comparing a self-hosted agent against a hosted model API for internal work.

Frequently asked questions

Is Hermes Agent free to use?

Hermes Agent is released under the MIT licence, according to the README. You still need to pay for or provide your own model provider or API access, and the README mentions optional paid options such as Nous Portal.

What do I need to run Hermes Agent?

The README lists Linux, macOS, WSL2 or native Windows with PowerShell as supported environments. The Windows installer sets up Python 3.14 for you. You will also need access to a model provider.

Does Hermes Agent work on Windows without WSL?

Yes. The README says native Windows runs the CLI, gateway, TUI and tools without WSL, and it installs with a PowerShell command. WSL2 also works with the Linux command.

How do I switch models in Hermes Agent?

Run hermes model to choose a provider and model. The README says switching does not require code changes.

Is Hermes Agent private?

The README does not describe data handling in detail. Your model and tool choices determine where data goes, so review the providers and backends you enable before sending sensitive information.

What are alternatives to Hermes Agent?

The source lists Open Interpreter, AutoGPT, OpenHands and Aider as comparable projects. Each focuses on different workflows, so compare them against the features you need.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Hermes Agent suits developers who want a personal agent they host and control, and who are comfortable with terminal installs and API keys. If you want a zero-setup hosted product or a documented privacy guarantee, pick a hosted service or another tool instead.

Install options & downloads