How to Run Hermes Agent on Zo

Hermes Agent is an open-source AI agent framework from Nous Research. It creates skills from experience, refines them through continued use, and builds a persistent model of you across sessions. It has its own messaging gateway for Telegram, Discord, and more. It needs a server that stays on. Zo is that server.

Why run Hermes Agent on Zo

Hermes Agent is designed to run 24/7. Most people set it up on a VPS, which means provisioning a server, installing dependencies, configuring systemd, and maintaining the whole thing. On Zo:

• Managed services. Register Hermes as a service and Zo keeps it running. Automatic restarts, log persistence, no systemd configuration.
• No server management. No OS updates, no firewall rules, no SSH hardening. Zo handles infrastructure.
• Zo's tools are available. Bridge Zo's web search, Gmail, Calendar, Drive, image generation, and 100+ other tools into Hermes via MCP.
• Two agents, one machine. Zo's built-in AI handles your daily operations. Hermes experiments, learns, and builds skills. They complement each other.

What you'll need

• A Zo Computer account (any tier)
• An API key from an LLM provider (Anthropic, OpenAI, OpenRouter, Google, etc.)
• A messaging channel token (Telegram Bot Token, Discord Bot Token, or similar)

Step 1: Install Hermes Agent

Open Zo's terminal and run:

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

This installs the hermes CLI to ~/.local/bin/hermes.

Step 2: Run setup

hermes setup

The wizard walks you through:

• Selecting your LLM provider
• Entering your API key
• Choosing a model
• Setting up a terminal backend (Docker or local)

When it asks about sandboxed execution, Docker is recommended. Zo has Docker available.

Step 3: Test it

hermes

This starts the interactive CLI. Send a few messages to make sure it responds. Try asking it to create a file or run a command to verify tool use works.

Step 4: Register as a managed service

Register Hermes as a Zo service so it survives restarts.

Note the entrypoint: use hermes gateway run, not hermes gateway start. The start subcommand expects a systemd/launchd background service, which Zo doesn't use — it would crash in a restart loop. hermes gateway run runs the gateway in the foreground, which is exactly what a Zo managed service supervises.

Your Zo registers the service. It starts automatically, restarts on crash, and persists logs.

To check on it later:

Step 5: Connect a messaging channel

Hermes has a built-in messaging gateway for Telegram, Discord, and more.

hermes gateway install

Follow the prompts to add your bot token. For Telegram, you'll need a Bot Token from @BotFather. If you also want to message your Zo directly on Telegram (separate from Hermes), see Connect Telegram to Zo.

Authorize yourself on Telegram

Note: by default the gateway denies every user until you add yourself to an allowlist.

Before you complete this step, the gateway connects fine and your messages are received (you can ask Zo to inspect your Hermes logs). But each message is silently dropped and logged as Unauthorized user, so the bot never replies.

Note that Telegram authorizes by numeric user ID, not by @username. Setting the allowlist to your handle will never match. To find your numeric ID, ask Zo to inspect the logs after you've messaged your bot. Or you can message @userinfobot on Telegram — it replies with your ID.

Then ask Zo to add it to Hermes's config in ~/.hermes/.env:

# Comma-separated numeric user IDs allowed to DM the bot
TELEGRAM_ALLOWED_USERS=6995160255

# Default chat for scheduled/cron message delivery (also a numeric ID)
TELEGRAM_HOME_CHANNEL=6995160255

A few things worth knowing:

• TELEGRAM_ALLOWED_USERS controls direct messages. Group access is separate — the allowed_chats setting in ~/.hermes/config.yaml governs which group/supergroup chats the bot responds in, and won't help with DMs.
• Values in ~/.hermes/.env are loaded with override priority, so a value there wins over an environment variable set on the service. Edit the .env file to be sure your change sticks.
• To allow anyone without an allowlist (not recommended), set GATEWAY_ALLOW_ALL_USERS=true instead.

Test by sending a message to your bot.

Step 6: Connect Zo's tools (optional)

This bridges Zo's tools into Hermes so it can use web search, email, calendar, and everything else Zo has access to.

• In Settings > Advanced, create an access token
• Save it as a secret: ZO_ACCESS_TOKEN = your token

After this, Hermes can call Zo's tools as MCP actions. Web search, Gmail, Calendar, Drive, image generation, all available inside Hermes.

How Hermes and Zo work together

Hermes Agent learns. It creates skills from successful task completions and reuses them. It builds a model of your preferences across sessions. That makes it good for specialized, repetitive tasks that benefit from accumulated experience.

Zo's built-in AI is good at breadth. It has native integrations, scheduled agents, multi-channel communication, website hosting, and a full tool ecosystem.

Here's where it gets interesting: both agents live on the same machine, and both expose APIs that the other can call. They can delegate to each other like partners.

Hermes delegates to Zo

Connect Hermes to the Zo MCP server or the Zo/Ask API, and Hermes can call upon your Zo agent to handle tasks outside its domain. Hermes is deep in a code review and needs to search the web for a library's changelog? It asks Zo. Hermes finishes a customer support analysis and needs to email the summary? It delegates to Zo. Hermes doesn't need to have its own email integration or web search. It calls Zo's.

Zo delegates to Hermes

Hermes Agent includes a built-in API server that follows the OpenAI format. That means your Zo can call Hermes like any other API: send a task, get a response.

Enable it by adding these to Hermes's config (~/.hermes/.env):

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key
API_SERVER_PORT=8642

Save the key as a Zo secret so your Zo can authenticate:

Now your Zo can send tasks to Hermes. Since both run on the same machine, the call is local and fast:

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "messages": [{"role": "user", "content": "Review the latest PR on my project and summarize the changes"}]
  }'

Hermes processes the request using its full toolset: terminal, files, web search, memory, and any skills it has learned. The response comes back to your Zo, which can then email it, text it, or act on it.

For ongoing conversations with Hermes, use the Responses API with named conversations:

curl http://localhost:8642/v1/responses \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "input": "Review the latest changes in /home/workspace/Code/myproject",
    "conversation": "code-review",
    "store": true
  }'

This means Hermes remembers context across multiple calls in the same conversation. Your Zo can follow up, ask for clarifications, or request deeper analysis.

The real payoff is scheduled delegation:

Your Zo orchestrates the schedule and delivery. Hermes does the specialized work. Neither agent needs to be good at everything. They cover each other's gaps.

Two agents, one machine

This is the real power of running Hermes on Zo. They're not separate services in separate clouds. They share the same filesystem, the same network, the same secrets. Communication between them is localhost: no latency, no auth tokens crossing the internet, no egress costs.

Your Zo handles daily operations: email, calendar, website, automations. Hermes handles the domains where accumulated experience matters: code review, research synthesis, customer support analysis. Both call on each other as needed, like partners sharing an office.

Most people start with Zo handling everything via scheduled agents and add Hermes when they find a domain that benefits from the learning loop. Over time, Hermes builds skills that make it increasingly good at its specialty, while Zo keeps the rest of your digital life running. You can also run Claude Code on the same machine for coding tasks, giving you three agents with different strengths on one server.

Troubleshooting

• "hermes: command not found": Make sure ~/.local/bin is in your PATH. Run export PATH="$HOME/.local/bin:$PATH" or add it to your .bashrc.
• Docker not available: Run docker info to check. If Docker isn't running, tell your Zo to start it. Alternatively, use local execution mode during setup (less isolation but works without Docker).
• Gateway won't start: Check that your bot token is correct with hermes gateway status. If it shows errors, reconfigure with hermes gateway install.
• Telegram bot connects but never replies: This is almost always the allowlist. Check the logs with tail -f /root/.hermes/logs/agent.log for Unauthorized user: <id> (<name>). Add that exact numeric ID to TELEGRAM_ALLOWED_USERS in ~/.hermes/.env (a numeric ID, not your @username), then restart the service. Remember TELEGRAM_ALLOWED_USERS covers DMs, while allowed_chats in ~/.hermes/config.yaml covers groups.
• Service keeps crashing: Check logs with tail -f /dev/shm/hermes-gateway.log. The most common cause is registering the service with hermes gateway start (which expects systemd/launchd) instead of hermes gateway run. Other causes: an expired API key or rate limiting from the LLM provider.
• Hermes can't reach Zo tools: Verify ZO_ACCESS_TOKEN is saved in Settings > Advanced and run mcporter list to check the bridge is active.
• Hermes vs. OpenClaw: Both are open-source agent frameworks that run on Zo. OpenClaw has a larger plugin ecosystem and community. Hermes has the learning loop and skill creation. Run OpenClaw on Zo if you want that instead.