How to Set Up Hermes Agent

Hermes Agent is an open-source AI agent framework from Nous Research that can run in your terminal, through messaging platforms, and as a background service. It supports many model providers, toolsets, persistent memory, skills, scheduled jobs, MCP servers, and gateway integrations such as Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, Home Assistant, and more.

This guide walks through a straightforward setup: install Hermes, choose a model provider, verify the installation, enable tools, and optionally run it through a messaging gateway.

1. Install Hermes Agent

The quickest installation path is the official install script:

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

After installation, open a new shell if needed so the hermes command is available on your PATH.

2. Start the setup wizard

Run the setup wizard to configure your model provider, credentials, terminal backend, gateway options, and core agent settings:

hermes setup

You can also configure a specific area directly:

hermes setup model
hermes setup terminal
hermes setup gateway
hermes setup tools
hermes setup agent

3. Choose a model provider

Hermes is provider-agnostic. You can use OpenRouter, Anthropic, OpenAI-compatible endpoints, Nous Portal, DeepSeek, Google Gemini, xAI, Hugging Face, Kimi, DashScope, MiniMax, local endpoints, and other supported providers.

To choose or change the active provider and model interactively, run:

hermes model

For providers that need credentials, use the authentication manager:

hermes auth
hermes auth add PROVIDER
hermes auth list

API keys and secrets live in Hermes' environment file, while normal settings live in the config file. You can find those paths with:

hermes config path
hermes config env-path

4. Verify the installation

Before relying on the agent, run the health checks:

hermes doctor
hermes status

If Hermes reports missing dependencies or configuration problems, the doctor command is the best first place to look. Some issues can be fixed automatically with:

hermes doctor --fix

5. Start using Hermes in the terminal

To open an interactive Hermes session, run:

hermes

For a one-off prompt from the shell, use:

hermes chat -q "Summarise the files in this project"

You can also select a model or provider for a specific run:

hermes chat -q "Explain this repo" --provider openrouter --model anthropic/claude-sonnet-4

6. Enable the tools you need

Hermes becomes more useful when the right toolsets are enabled. Toolsets can provide web access, browser automation, file editing, terminal access, image generation, vision, cron jobs, memory, session search, delegation, and more.

Use the interactive tool manager:

hermes tools

Or list, enable, and disable toolsets directly:

hermes tools list
hermes tools enable web
hermes tools enable terminal
hermes tools enable file
hermes tools disable browser

Tool changes normally take effect in a new session. In chat, start fresh with /reset.

7. Add skills for repeatable workflows

Skills are reusable instructions that Hermes can load when a task matches a known workflow. They are useful for coding practices, cloud operations, research workflows, media tasks, and project-specific procedures.

hermes skills list
hermes skills browse
hermes skills search github
hermes skills install SKILL_ID

You can preload skills at startup:

hermes -s hermes-agent

8. Configure the messaging gateway

If you want Hermes in Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, Home Assistant, or another supported platform, configure the gateway:

hermes gateway setup

Then run it in the foreground to test:

hermes gateway run

Once it works, install and start it as a background service:

hermes gateway install
hermes gateway start
hermes gateway status

On Linux servers or Raspberry Pi setups, if the gateway stops when you log out of SSH, enable user service lingering:

sudo loginctl enable-linger $USER

9. Useful slash commands

Inside a Hermes session, slash commands help manage the runtime quickly:

• /help — show available commands
• /new or /reset — start a fresh session
• /model — view or change the model
• /tools — manage tools
• /skills — search or install skills
• /status — show session status
• /cron — manage scheduled jobs
• /restart — restart the gateway from a gateway chat

10. Troubleshooting checklist

• Run hermes doctor to check configuration and dependencies.
• Run hermes auth list to confirm credentials are available.
• Run hermes tools list to confirm the required toolsets are enabled.
• Use /reset after changing tools or skills.
• Restart the gateway after config changes with hermes gateway restart or /restart.
• Check gateway logs at ~/.hermes/logs/gateway.log if a messaging platform is silent.

Recommended first setup path

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
hermes model
hermes doctor
hermes tools
hermes

For the latest official instructions, use the Hermes Agent documentation: https://hermes-agent.nousresearch.com/docs/.