How to Set Up Hermes Agent From Scratch

Hermes Agent is an open-source (MIT-licensed) AI agent built by Nous Research. It runs on your own infrastructure, whether that is a laptop, a VPS, a Docker container, or a serverless backend. The agent connects to over 200 LLM models through providers like OpenRouter, OpenAI, Anthropic, and NVIDIA NIM, and it communicates across 20+ messaging platforms including Telegram, Discord, Slack, WhatsApp, Signal, and email.

What sets Hermes apart from simpler CLI wrappers is its learning loop. The agent creates skills from successful multi-step tasks, improves those skills over subsequent runs, and maintains persistent memory across sessions using FTS5 search and LLM summarization. Skills follow the agentskills.io open standard, so they are portable and shareable through the Skills Hub, which currently hosts 672 skills across four registries.

Most existing setup guides stop at pip install and a single chat prompt. That leaves you with an agent that forgets its files on restart, cannot reach your team on Telegram, and has no access to community skills. This walkthrough covers all five stages: install, model configuration, tool activation, gateway setup, and persistent storage so the agent's output actually reaches humans.

The one-line installer handles all dependencies automatically. It installs uv (the Python package manager), Python 3.11, Node.js v22, ripgrep, and ffmpeg. The only prerequisite is Git.

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

After the script finishes, reload your shell:

source ~/.bashrc

Or if you use zsh:

source ~/.zshrc

Verify the installation by running:

hermes --version

Where Files Live

The installer creates a per-user layout:

• Agent code: ~/.hermes/hermes-agent/
• Binary symlink: ~/.local/bin/hermes
• Configuration and data: ~/.hermes/
• Skills directory: ~/.hermes/skills/

If you run the installer with sudo, paths shift to system-wide locations (/usr/local/lib/hermes-agent/ and /usr/local/bin/hermes). For most single-user setups, the default per-user installation is simpler to manage.

Supported Platforms

The installer works on Linux, macOS, and WSL2. Android users can install through Termux with the same curl command. Native Windows is not supported, so Windows users should set up WSL2 first.

If the hermes command is not found after installation, check that ~/.local/bin is in your PATH. On most systems the installer adds it automatically, but some shell configurations need a manual export:

export PATH="$HOME/.local/bin:$PATH"

Hermes Agent does not bundle its own model. You connect it to any provider that serves chat completions. Run the interactive model setup:

hermes model

This walks you through selecting a provider and entering your API key. Supported providers include Nous Portal, OpenRouter, OpenAI, Anthropic, NVIDIA NIM, DeepSeek, Hugging Face, GitHub Copilot, and many more. OpenRouter alone gives access to over 200 models.

Model Requirements

Hermes requires a model with at least 64,000 tokens of context. Models with smaller context windows cannot maintain enough working memory for multi-step tool-calling workflows and will be rejected at startup. Most current-generation models from OpenAI, Anthropic, and the popular open-weight families (Llama 3, Mixtral, Command R+) clear this threshold comfortably.

Manual Configuration

If you prefer to skip the interactive wizard, set values directly:

hermes config set model anthropic/claude-sonnet-4-6
hermes config set OPENROUTER_API_KEY sk-or-your-key-here

Secrets go to ~/.hermes/.env. Non-secret settings go to ~/.hermes/config.yaml. The CLI routes values to the right file automatically.

Switching Providers Later

There is no lock-in. Run hermes model again at any time to switch providers. Your skills, memory, and configuration carry over because they are stored independently from the model connection.

Out of the box, Hermes has terminal access, file operations, and web browsing. The tools command lets you toggle capabilities per platform:

hermes tools

This shows which tool groups are active for the CLI, messaging gateway, and API interfaces. You can enable or disable terminal access, file system operations, and other tool categories depending on how much autonomy you want the agent to have.

Add MCP Servers

Hermes supports Model Context Protocol servers for extended capabilities. Add them to ~/.hermes/config.yaml:

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_your_token"

After adding an MCP server, the agent can use its tools in any session. This is where connecting a Fastio MCP server becomes useful: instead of files living only on the host machine, the agent reads and writes to a cloud workspace that humans can access through a browser, branded shares, or their own MCP client.

mcp_servers:
  fastio:
    command: npx
    args: ["-y", "@anthropic-ai/mcp-server-fetch"]
    env:
      FASTIO_API_KEY: "your_api_key"

Fastio's MCP server exposes workspace, storage, AI, and workflow operations through a single endpoint. Files uploaded by the agent are automatically indexed for semantic search when Intelligence is enabled on the workspace. The Business Trial includes 50 GB storage, included credits, and five workspaces with no credit card required.

Browse and Install Community Skills

The Skills Hub hosts 672 skills across four registries: 89 built-in, 62 official optional, and 521 community-contributed skills spanning 17 categories from DevOps to creative writing.

hermes skills browse
hermes skills search kubernetes
hermes skills install official/security/1password

Skills are on-demand knowledge documents that the agent loads using progressive disclosure. At Level 0, skills_list() returns lightweight metadata (roughly 3,000 tokens). The agent only loads full skill content when it actually needs the instructions, keeping token costs low.

All hub-installed skills pass through a security scanner that checks for data exfiltration, prompt injection, and destructive commands. Trust levels run from builtin (highest) down through official, trusted, and community.

Agent-Generated Skills

One of Hermes's defining features is that it creates its own skills. After completing a complex task (typically five or more tool calls), the agent writes a SKILL.md file capturing the procedure it discovered. On subsequent runs, it loads that skill instead of rediscovering the workflow. You can review, edit, or delete agent-created skills in ~/.hermes/skills/.

Give Your Hermes Agent a Persistent Workspace

Fastio workspaces store files your agent creates and make them searchable, shareable, and accessible to your whole team. generous storage, no credit card, works with any MCP client.

Start 14-Day Trial

The messaging gateway is a single background process that connects Hermes to all your configured platforms simultaneously. Run the setup wizard:

hermes gateway setup

The wizard walks through each platform. For Telegram, you paste a BotFather token and your numeric user ID. For Discord, you provide a bot token. For Slack, you configure a Slack app. The wizard writes credentials to ~/.hermes/.env automatically.

Supported platforms include Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, and Microsoft Teams.

Start the Gateway

hermes gateway

Once running, the gateway exposes an OpenAI-compatible API on port 8642 and a web dashboard on port 9119. The agent responds to messages on all configured platforms, handles file attachments, processes voice messages, and maintains session context across conversations.

Check Gateway Status

hermes gateway status

This shows which platform connections are active, any authentication errors, and the uptime of each bot.

Scheduled Automations

The gateway also runs the built-in cron scheduler for unattended tasks. You can set up recurring jobs that execute while the gateway is running, like daily report generation, periodic file backups, or scheduled data pulls. This makes the gateway the long-running process that keeps your agent available around the clock.

Subagent Delegation

For complex workflows, Hermes can spawn isolated parallel workstreams using RPC-based tool calling. Each subagent gets its own context and tool access, and results flow back to the parent agent. This is useful for tasks like researching multiple topics simultaneously or processing batches of files in parallel.

This is the step most setup guides skip. By default, Hermes stores files on the host machine's filesystem. That works fine for local experiments, but it breaks down in three scenarios: container restarts wipe ephemeral storage, team members cannot access files without SSH access to the host, and there is no searchable index across the agent's output.

The cleanest solution is connecting a cloud workspace that the agent writes to and humans read from. Several options work here.

Local or self-hosted storage like a mounted NFS share or Nextcloud instance keeps files on infrastructure you control. The tradeoff is setup complexity and the lack of built-in search or sharing workflows.

Object storage like S3 or Google Cloud Storage handles scale well but requires custom tooling to make files browsable and shareable with non-technical team members.

Fastio workspaces are purpose-built for this handoff pattern. The agent writes files through the MCP server or API. Humans browse them in a web interface, search by meaning with Intelligence Mode, and share externally through branded Send links. When the agent finishes a project, ownership transfer lets you hand the entire workspace to a client or team lead while keeping admin access.

Why Persistent Storage Matters for Agents

Hermes Agent's memory system (session history, FTS5 search, LLM summaries) handles conversational context well. But generated artifacts, reports, exported data, images, and documents need a storage layer that outlives any single session. Without one, you end up manually copying files off the host after every run, losing track of what the agent produced last week, and rebuilding context for the next session.

With a connected workspace, the agent's output is immediately available to anyone with access. A developer can review generated code. A project manager can download reports. A client can browse deliverables through a branded portal. The agent created the files; humans consume them through whatever interface fits their workflow.

Fastio's Business Trial provides 50 GB of storage, five workspaces, and included credits with no credit card and no expiration. Files are automatically indexed for semantic search and RAG chat when Intelligence is enabled, so you can ask questions about the agent's output without opening individual files.

Common Issues

If something is not working, the built-in diagnostic tool catches most problems:

hermes doctor

This checks your configuration, API key validity, tool access, and gateway connectivity. It returns specific remediation steps for each issue it finds.

"hermes: command not found" after installation means your shell did not reload. Run source ~/.bashrc (or source ~/.zshrc) and check that ~/.local/bin is in your PATH.

"API key not set" means the model configuration did not save correctly. Run hermes model again or set the key directly with hermes config set.

Missing config after an update can happen when the config schema changes between versions. Run hermes config check followed by hermes config migrate to reconcile.

Useful Day-to-Day Commands

hermes --tui             # Modern terminal UI with autocomplete
hermes --continue        # Resume your last conversation
hermes sessions list     # View saved sessions
hermes skills check      # Check for upstream skill updates
hermes skills update     # Install updated skills

The TUI mode is worth trying if you spend significant time in the CLI. It adds multiline editing, slash-command autocomplete, and streaming tool output in a structured layout.

Voice Mode

If you want hands-free interaction, install the voice dependencies:

pip install "hermes-agent[voice]"

Activate it in any session with /voice on and record with Ctrl+B. It uses faster-whisper for local speech-to-text, so audio never leaves your machine.

Where to Go From Here

Once the base setup is working, the natural next steps are writing custom skills for your specific workflows, configuring scheduled automations through the gateway's cron system, and exploring subagent delegation for parallel workloads. The Hermes Agent documentation covers each of these in detail.