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. Zo has all the same features built into your always-online cloud computer.

If you already use Hermes, or just want to try it out, Zo is a great place to host your Hermes.

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.
• Extend Zo with Hermes. Let your Zo use Hermes and access the Hermes ecosystem of tools and skills from your Zo.
• Zo's tools are available. Bridge Zo's web search, Gmail, Calendar, Drive, image generation, and 100+ other tools into Hermes via MCP.

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.

Set up Hermes's tools

Separately from the language model, Hermes has its own built-in tools — terminal, files, code execution, and a browser all work out of the box. A few tools (web search, image generation, voice/TTS, and hosted browser automation) run through the Nous Tool Gateway, and you choose how to power them.

Easiest: a Nous Portal subscription. One Nous Portal subscription covers both the language models and the Tool Gateway, so web search, image generation, and the rest light up without juggling separate accounts. During hermes setup, choose Nous Portal and sign in.

One gotcha worth knowing: being signed in to Nous for models does not automatically turn on the Tool Gateway. If hermes portal tools shows tools like image generation as "not configured" even though you're logged in, ask Zo to re-link your Nous credentials to the gateway and restart the hermes-gateway service. After that, tools like image generation report "via Nous Portal" and become available.

Alternative: bring your own API keys. If you'd rather not use Portal, you can point individual tools at your own provider keys — for example a FAL key for image generation, or a search-provider key for web search. Save each key as a secret in Zo Settings > Advanced, and ask Zo to configure your Hermes.

Either way, the language-model choice from the setup wizard is independent — you can run any provider's model and still use Portal or your own keys for tools.

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: Let Zo use Hermes

Hermes Agent includes a built-in OpenAI-compatible API server that runs alongside the messaging gateway. That gives Zo a clean way to use Hermes as a subagent: Zo sends a task to a localhost HTTP endpoint, Hermes works with its own tools, memory, MCP servers, and skills, then Zo receives the result and decides what to do next.

Before wiring this up, ask Zo to update Hermes and inspect the running API surface. The API server has been moving quickly, and older installs may not have the newer discovery, runs, or session endpoints.

A good Zo setup flow is:

1. Run hermes update --check and upgrade if needed.
2. Enable the API server in ~/.hermes/.env.
3. Restart the hermes-gateway service.
4. Query /v1/capabilities, /v1/skills, and /v1/toolsets so Zo can document what this Hermes instance can actually do.
5. Create a Zo Skill that wraps the local Hermes API call.
6. Try one simple test prompt so you know Zo can reach Hermes.

Enable the API server

Add these to ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=hermes-local-dev-key-change-me
# Optional; defaults shown here for clarity
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642

Then restart the gateway. If you registered Hermes as a Zo service earlier in this tutorial, ask Zo to restart that service:

Keep the API server bound to 127.0.0.1 unless you intentionally want another machine to call it. The API key protects the endpoint, but the endpoint can run Hermes with its full toolset, including terminal and file access. Localhost-only is the right default on Zo.

You can verify the server with:

curl http://127.0.0.1:8642/health
API_SERVER_KEY=$(grep '^API_SERVER_KEY=' ~/.hermes/.env | cut -d= -f2-)
curl http://127.0.0.1:8642/v1/capabilities \
  -H "Authorization: Bearer $API_SERVER_KEY"

Two easy gotchas:

• The gateway must run in the foreground under Zo's service supervisor. Use hermes gateway run, not hermes gateway start.
• API_SERVER_KEY is required even on localhost. It lives in ~/.hermes/.env; you do not need to create a separate Zo secret unless you want to call Hermes from some other script or service.

Create a Skill

The cleanest integration for Zo to use Hermes is a Skill, because it gives future Zo prompts a durable, reusable entrypoint instead of making Zo rediscover the API each time.

The underlying call can be as small as this:

API_SERVER_KEY=$(grep '^API_SERVER_KEY=' ~/.hermes/.env | cut -d= -f2-)
curl http://127.0.0.1:8642/v1/responses \
  -H "Authorization: Bearer $API_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "conversation": "zo-hermes",
    "input": "Say hello from Hermes."
  }'

Using /v1/responses with a conversation name is useful for subagent work because Hermes can keep context across calls without Zo having to manually replay the transcript. For one-off tasks, use a fresh conversation name. For a project-specific Hermes thread, reuse something stable like code-review-hostagent or research-hermes-docs.

Ask Zo to expose a few discovery commands in the skill wrapper:

After the skill exists, using Hermes from Zo should feel like this:

A successful setup returns:

hello from hermes

That simple test is worth doing. It proves the important pieces are aligned: Hermes is upgraded, the API server is enabled, Zo can read the key from Hermes's own .env file, and the skill can return Hermes's response.

Step 7: Connect Zo's tools to Hermes

This lets Hermes use Zo's tools through MCP: web search, page reading, Gmail, Calendar, Drive, Space routes, image generation, and more. You do not need to create a new token by hand. Your Zo already has a host token available on the server; ask Zo to copy it into Hermes's environment and add Zo as an MCP server.

If you want to check the config yourself, the relevant part of ~/.hermes/config.yaml should look like this:

mcp_servers:
  zo:
    url: "https://api.zo.computer/mcp"
    headers:
      Authorization: "Bearer ${ZO_CLIENT_IDENTITY_TOKEN}"
    tools:
      include:
        - web_search
        - web_research
        - read_webpage
        - tool_docs
      prompts: false
      resources: false

You can ask Zo to add more tools later. Start small, especially for tools that can send messages, change files, or publish things. Add Gmail, Calendar, Drive, Space, or publishing tools only when Hermes needs them for a specific workflow.

After the gateway restarts, ask Zo to run:

hermes mcp list
hermes mcp test zo

Then try one plain-language test:

After this, Hermes can call Zo's tools as MCP actions. Zo remains the safer outer orchestrator for scheduling, notifications, websites, and cross-app work; Hermes can call Zo tools when it needs them inside a longer task.

Troubleshooting

• "hermes: command not found": Make sure ~/.local/bin is in your PATH. Run export PATH="$HOME/.local/bin:$PATH" or ask Zo to add it to your shell profile.
• Gateway won't start: Check the logs with tail -f /dev/shm/hermes-gateway.log and tail -f /dev/shm/hermes-gateway_err.log. If Zo is supervising the service, the entrypoint should be hermes gateway run or hermes gateway run --replace, not hermes gateway start.
• Gateway says another Hermes instance is already running: Update the Zo service entrypoint to hermes gateway run --replace, or stop the old Hermes process before restarting the service.
• Telegram bot connects but never replies: This is usually the allowlist. Check the logs 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. TELEGRAM_ALLOWED_USERS covers direct messages; allowed_chats in ~/.hermes/config.yaml covers groups.
• Hermes API calls return 401: API_SERVER_KEY is required even on localhost. It lives in ~/.hermes/.env; use that same value when calling Hermes's API.
• Hermes can't see Zo tools: Ask Zo to check that ZO_CLIENT_IDENTITY_TOKEN exists in ~/.hermes/.env, that ~/.hermes/config.yaml has an mcp_servers.zo entry pointing to https://api.zo.computer/mcp, and that hermes mcp test zo succeeds. Restart hermes-gateway after editing the config.