Service helper that sets up a Hermes Agent gateway and Hermes Desktop remote backend in a box.

​
Quick Start

zomg hermes build-base
zomg hermes create my-agent
create creates a persistent HERMES_HOME data volume, starts the Hermes gateway, starts the Hermes dashboard backend, enables the OpenAI-compatible API server, and waits for ports 8642 and 9119.

​
Create

zomg hermes create my-agent
What it sets up:
  • Box tag: service=hermes
  • Data volume mounted at /var/lib/hermes
  • Hermes gateway process
  • API server on 0.0.0.0:8642
  • Hermes dashboard backend on 0.0.0.0:9119
  • API key: generated by default and printed in the connect hint
  • Default model name: hermes-agent
  • Default Desktop login: admin / hermes
Override the API key: 
zomg hermes create my-agent --api-key "$HERMES_API_KEY"
Override the Desktop remote-backend login: 
zomg hermes create my-agent \
  --dashboard-user admin \
  --dashboard-password "$HERMES_DASHBOARD_PASSWORD" \
  --dashboard-secret "$HERMES_DASHBOARD_BASIC_AUTH_SECRET"
Publish the dashboard for Hermes Desktop in one step: 
zomg hermes create my-agent \
  --publish my-agent \
  --dashboard-password "$HERMES_DASHBOARD_PASSWORD"

​
Connect

From another box in the same project: 
curl -fsS \
  -H "Authorization: Bearer $HERMES_API_KEY" \
  http://my-agent.default:8642/v1/models
OpenAI-compatible base URL: 
http://my-agent.default:8642/v1

​
Hermes Desktop Remote Backend

Hermes Desktop connects to the Hermes dashboard backend, not directly to the OpenAI-compatible API server. Internal Zomg URL: 
http://my-agent.default:9119
Public URL after publishing: 
zomg hermes publish my-agent my-agent
Use the printed https://... URL in Hermes Desktop:
  1. Open Settings.
  2. Go to Gateway.
  3. Set Remote URL to the published dashboard URL.
  4. Sign in with the dashboard username/password.
  5. Save and reconnect.
For public internet access, prefer OAuth or a VPN. The default username/password path is for development and trusted networks.

​
Compose

name: agent-stack

addons:
  - use: hermes
    as: agent

services:
  app:
    port: 8080
    command: ["python3", "-u", "-m", "http.server", "8080"]
    env:
      HERMES_API_BASE_URL: ${addons.agent.api_base_url}
      HERMES_API_KEY: ${addons.agent.api_key}
      HERMES_MODEL: ${addons.agent.model}
      HERMES_DESKTOP_REMOTE_URL: ${addons.agent.desktop_remote_url}
Available compose outputs:
  • host
  • port
  • url
  • api_base_url
  • api_key
  • model
  • dashboard_port
  • dashboard_user
  • dashboard_password
  • desktop_remote_url

​
Snapshot + Clone

zomg hermes snapshot my-agent
zomg hermes create my-agent-copy --fork my-agent
Snapshots capture Hermes config, memory, sessions, logs, and other state under /var/lib/hermes.

​
Stop

zomg hermes stop my-agent
Stops the gateway and dashboard processes while preserving the data volume.

​
Verification

Run: 
./crates/zomg-hermes/verify.sh
This builds the local helper, ensures the Hermes base exists, creates an agent, checks the API server and dashboard backend, clones the agent state, validates tag-filtered listing, and verifies helper cleanup.