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: 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.

Test by sending a message to your bot.

Step 5: Register as a managed service

This is the key step. Instead of using systemd or running Hermes in a tmux session, register it as a Zo service so it survives restarts.

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

To check on it later:

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.
• Service keeps crashing: Check logs with tail -f /dev/shm/hermes-gateway.log. Common cause is 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.