Hermes Agent

What is Hermes Agent?

Hermes Agent is an open-source autonomous AI agent runtime built by Nous Research. It runs persistently as a gateway process - always available to receive messages, execute scheduled tasks, and reason over its accumulated memory and task history.

Unlike stateless chat interfaces, Hermes Agent retains a persistent world model: memory is stored and searchable across sessions, tasks are tracked on a built-in kanban board, and cron jobs fire on schedule regardless of whether a browser is open. It connects to 20+ messaging platforms (Telegram, Discord, Slack, Teams, and more) through a unified gateway, integrates with 60+ built-in tools, and supports Model Context Protocol (MCP) for extending capabilities further.

Hermes Agent works with any major LLM provider - OpenRouter, Anthropic, OpenAI, or Google. Nous Portal subscribers can use hermes setup --portal for one-shot authentication that also opts into the Tool Gateway. At least one provider API key is required.

Coolify offers two deployment templates suited to different use cases. See Deployment Variants below to choose the right one.

Deploy on Coolify

Both templates use the same nousresearch/hermes-agent image and store all agent state in persistent volumes. The difference is how the web interface is delivered: as a separate companion container (WebUI), or built into the agent process itself (Dashboard).

Hermes Agent (with WebUI)

Deploys two containers:

Coolify auto-generates the following - no manual configuration needed:

• SERVICE_USER_HERMESWEBUI - WebUI login username
• SERVICE_PASSWORD_HERMESWEBUI - WebUI login password
• SERVICE_URL_HERMESWEBUI_8787 - Public URL for the chat interface

Uses four named volumes: hermes-home, hermes-skills, hermes-agent-src, hermes-workspace. The WebUI shares the hermes-home and hermes-workspace volumes with the agent for direct access to memory and the workspace directory.

Hermes Agent (Dashboard)

Deploys a single container with the built-in dashboard activated:

Coolify auto-generates the following - no manual configuration needed:

• SERVICE_USER_HERMESAGENT - Dashboard login username
• SERVICE_PASSWORD_HERMESAGENT - Dashboard login password
• SERVICE_BASE64_64_HERMESAGENT - Session signing secret (64-character random string)
• SERVICE_URL_HERMESAGENT_9119 - Public URL for the dashboard

Uses a single named volume (hermes-home) that covers all persistent state: agent config, API keys, auth tokens, memory, kanban board, profiles, cron jobs, logs, hooks, plans, skins, skills, workspace files, SSH keys, and pip-installed packages.

Deployment Variants

Choose Hermes Agent (with WebUI) when you want a dedicated web chat interface. The hermes-webui container provides a chat-first experience and releases independently from the agent, so you can update the UI without touching the agent process.

Choose Hermes Agent (Dashboard) when you want the simplest possible deployment, or when running the agent that manages your Coolify setup. All state is in one volume, there are no inter-container dependencies to manage, and the dashboard surfaces memory, the task board, cron jobs, and installed skills in one place. This is the recommended option for self-hosting Hermes as a Coolify automation agent.

Environment Variables

LLM Providers

At least one provider key is required for the agent to function. The agent selects the active provider from your config at runtime.

Web Search (Optional)

Agent Behavior

WebUI Variant - Additional Variables

Dashboard Variant - Additional Variables

What to do after deploying

Coolify deploys the containers, but the agent still needs a one-time configuration step before it can respond to messages. You run this from the container terminal in Coolify.

Step 1 - Open the web interface

Click Open in Coolify to open the interface. For the WebUI variant this is the hermes-webui chat interface on port 8787; for the Dashboard variant it is the built-in dashboard on port 9119.

Log in with the auto-generated credentials from the Environment Variables tab:

• WebUI: SERVICE_USER_HERMESWEBUI and SERVICE_PASSWORD_HERMESWEBUI
• Dashboard: SERVICE_USER_HERMESAGENT and SERVICE_PASSWORD_HERMESAGENT

Step 2 - Run the setup wizard

Open a terminal into the hermes-agent container from Coolify's Terminal tab and run:

hermes setup

The wizard walks you through selecting an LLM provider and model, configuring optional tools, and setting up messaging platform integrations. This is the recommended starting point for every fresh deploy.

If you are a Nous Portal subscriber, you can skip the individual provider prompts entirely:

hermes setup --portal

This authenticates via OAuth, sets Nous as the inference provider, and opts into the Tool Gateway in a single step.

After any setup command, restart the hermes-agent container - the gateway reads config.yaml only at startup.

Step 3 - Run the doctor check

hermes doctor --fix

This auto-repairs common configuration issues. Two warnings are expected in a Docker environment and can be ignored:

• "Add ~/.local/bin to your PATH" - the symlink is created but the PATH fix does not persist across container restarts. The hermes command still works.
• "Run hermes setup to configure missing API keys" - fires if any optional tool keys (EXA, Tavily) are unset. If Firecrawl is configured, web search is fully functional.

Step 4 - Enable Firecrawl web search (optional)

Firecrawl gives Hermes the ability to search the web and extract full page content from URLs, including JavaScript-rendered pages. Without it, the web tool is unavailable.

1. Sign up at firecrawl.dev - the free tier includes 500 pages/month.
2. Add FIRECRAWL_API_KEY to the Environment Variables tab in Coolify and redeploy, or configure it interactively from the terminal:

   hermes setup tools

To use a self-hosted Firecrawl instance on your Docker network, set FIRECRAWL_API_URL to http://<service-name>:3002 and ensure HERMES_ALLOW_PRIVATE_URLS=true.

Step 5 - Connect a messaging platform (optional)

Hermes connects to Telegram, Discord, Slack, Microsoft Teams, and more. To configure any messaging integration, run the gateway setup wizard from the container terminal:

hermes gateway setup

The wizard prompts you for the platform-specific credentials and configures the integration. For Telegram specifically, you will need:

1. A bot token from @BotFather on Telegram - send /newbot, follow the prompts, copy the token.
2. Your Telegram user ID from @userinfobot - send any message to it and it returns a plain number like 987654321.

After running hermes gateway setup, add your user ID restriction to Coolify's Environment Variables tab:

Then redeploy. Your Telegram bot token is stored in the persistent volume by the setup wizard - it does not need to go in Coolify's environment variables.

Plugins

Hermes ships with opt-in bundled plugins. Nothing loads until you explicitly enable it. Manage plugins from the container terminal:

hermes plugins         # interactive UI - toggle with SPACE, confirm with ENTER
hermes plugins list    # show all plugins and their current state
hermes plugins enable <plugin-name>
hermes plugins disable <plugin-name>

Notable bundled plugins:

Enable disk-cleanup:

hermes plugins enable disk-cleanup

Plugin settings are written to the persistent volume and survive container restarts.

Persistent Memory (optional)

Hermes supports external memory providers that build a cross-session user model and inject it at the start of each conversation. Several providers are available: Honcho, mem0, Hindsight, and others. Configure any provider from the terminal:

hermes memory setup    # interactive provider selection and configuration
hermes memory status   # show active provider and connection status

See the memory providers documentation for provider-specific setup guides.

Troubleshooting

The agent starts but never responds to messages The agent requires hermes setup to be run at least once to configure an LLM provider and model. Open a terminal in the hermes-agent container and run hermes setup. Restart the container after completing the wizard.

HTTP 404 errors from OpenRouter The model name is in the wrong format. OpenRouter requires provider/model-name (e.g., anthropic/claude-sonnet-4-5, moonshotai/kimi-k2.6). Run hermes model in the container terminal to update the model selection, then restart.

config.yaml changes not persisting / "Permission denied" errors Coolify's container terminal opens a root shell. If you run hermes commands without the agent being accessible as the correct user, config files may be written as root and become unreadable by the agent process. Run this to fix ownership, then restart:

chown -R 1000:1000 /home/hermes/.hermes   # WebUI variant
# or
chown -R 1000:1000 /opt/data              # Dashboard variant

API keys returning 401 after setting them in Coolify A stale .env file on the volume may be overriding Coolify's environment variables. Check for and remove stale values:

cat /home/hermes/.hermes/.env    # WebUI variant
# or
cat /opt/data/.env               # Dashboard variant

Remove any API key lines that conflict with what Coolify is injecting.

The hermes-webui container exits immediately (WebUI variant) The webui depends on hermes-agent passing its healthcheck (verifying the agent home directory exists). On first boot this takes 10-30 seconds. Docker restarts it automatically - this is normal. If it keeps failing, check the hermes-agent logs for startup errors.

Dashboard login fails / 401 errors (Dashboard variant) Retrieve your credentials from the Environment Variables tab - SERVICE_USER_HERMESAGENT and SERVICE_PASSWORD_HERMESAGENT. If SERVICE_BASE64_64_HERMESAGENT is missing or was deleted, let Coolify regenerate it and redeploy.

CSP violation warnings in logs when using Cloudflare Tunnel (WebUI variant) Cloudflare Tunnel injects an analytics beacon script that the hermes-webui Content Security Policy blocks. This is harmless - disposition: report means the interface is still fully functional - but the logs fill up. To stop it, disable Cloudflare Web Analytics injection for the Hermes WebUI hostname in your Cloudflare Zero Trust dashboard under Networks - Tunnels - [your tunnel] - Additional application settings.

Compression threshold warning in logs Open /home/hermes/.hermes/config.yaml (or /opt/data/config.yaml for the Dashboard variant) in the container terminal and add:

compression:
  threshold: 0.20

Restart the container.

"Skills Hub not initialized" warning Run once to initialize:

hermes skills list

The "Open" button in Coolify leads to an error page The Open button resolves to the first exposed URL. For the WebUI variant that is port 8787; for the Dashboard variant it is port 9119. Wait for the healthcheck on that port's container to pass, then refresh.

Firecrawl requests fail with connection errors If pointing FIRECRAWL_API_URL at a self-hosted Firecrawl on a Docker-internal hostname or Tailscale address, ensure HERMES_ALLOW_PRIVATE_URLS=true is set.

Key Files (inside the container)

Config changes require a container restart to take effect.

Links

• GitHub - Hermes Agent
• GitHub - Hermes WebUI
• Documentation
• Nous Research
• Firecrawl
• OpenRouter