hermes-telemetry

hermes-telemetry

Call-home telemetry reporter for managed Hermes Agent workers. Installs globally, asks where home is once, then runs a background job that phones in one imprint every 10 minutes: status, model, token usage, errors, browser health, and host health.

It knows where Hermes keeps its state: every imprint reads the configured model from $HERMES_HOME/config.yaml and the last 24 hours of token usage from $HERMES_HOME/state.db (Hermes' own session_model_usage table), so the fleet dashboard shows real numbers with no cooperation from the agent.

Install and run

npm install -g hermes-telemetry
hermes-telemetry

First run asks three questions:

Telemetry URL [https://8examples.com/hermes/telemetry]:
Access key (hmt_...): <token from your 8Examples admin>
Agent name (e.g. hermes1): hermes1

then starts the background job. Config is saved to ~/.hermes-telemetry/config.json (mode 600), so subsequent runs start straight away.

hermes-telemetry once         # send a single imprint now
hermes-telemetry imprint      # print the imprint that would be sent
hermes-telemetry usage-check  # model + 24h tokens straight from state.db
hermes-telemetry status       # daemon state + last sends
hermes-telemetry stop         # stop the background job
hermes-telemetry setup        # change URL / key / agent name

Admins issue access keys from the Fleet tab at 8examples.com/account.

Needs Node 22.13+ (it reads state.db with the built-in node:sqlite; on older Node the usage fields are simply omitted).

Zero-prompt installs

Set the environment instead and no config file or prompt is needed — this is how managed Hermes containers run it (as an s6 service inside the fleet image):

HERMES_TELEMETRY_TOKEN=hmt_...        # required
HERMES_TELEMETRY_AGENT=hermes1        # or HERMES_AGENT_NAME
HERMES_TELEMETRY_URL=https://8examples.com/hermes/telemetry   # optional, this is the default
HERMES_HOME=/opt/data                 # where Hermes keeps config.yaml + state.db (default ~/.hermes)

Environment variables beat the config file key by key.

What it sends

POST <url> with Authorization: Bearer <key>:

{
  "agents": [
    {
      "agent": "hermes1",
      "at": "2026-08-21T12:00:00.000Z",
      "status": "ok",
      "model": "anthropic/claude-opus-4-8",
      "tokens": { "input": 12000, "output": 3400, "total": 15400, "cacheRead": 9000, "cacheWrite": 0, "reasoning": 0 },
      "usage": { "windowHours": 24, "apiCalls": 41, "sessions": 3, "lastSeenAt": "2026-08-21T11:52:10.000Z" },
      "errors": [],
      "note": "free text",
      "host": {
        "hostname": "hermes-hermes1",
        "platform": "linux 7.0.0",
        "arch": "x64",
        "uptimeHours": 12.5,
        "load": [0.1, 0.2, 0.15],
        "memFreeMB": 2048,
        "memTotalMB": 8192
      },
      "browser": { "ok": true, "bin": "chrome", "url": "https://example.com/", "ms": 850 },
      "portmap": { "ok": true, "url": "https://hermes1.fusenv.com", "status": 200, "ms": 120 },
      "agent_info": { "name": "hermes-telemetry", "version": "0.1.0", "latest": "0.1.0", "upToDate": true }
    }
  ]
}

Letting the worker speak for itself

The reporter merges ~/.hermes-telemetry/status.json into every imprint, so the worker (or anything else on the machine) can override what it reads from Hermes' state:

{
  "status": "ok",
  "model": "anthropic/claude-opus-4-8",
  "tokens": { "input": 12000, "output": 3400 },
  "errors": [],
  "note": "processed 14 bookings today",
  "extra": { "queueDepth": 0 }
}

status may be ok, warn, or error; it drives the color of the worker's tile on the fleet dashboard.

Browser health check

Every imprint also exercises the machine's web browser: the reporter uses the same executable Hermes' browser tools launch (AGENT_BROWSER_EXECUTABLE_PATH) first, then searches PATH and Playwright's browser cache (/opt/hermes/.playwright in the official image, preferring the full browser over the headless shell), headless-loads a page that should always work — https://example.com/ by default — and verifies HTML comes back within 30 seconds. A failure appends a browser: ... line to errors, which turns the tile amber unless the worker has set its own status.

HERMES_TELEMETRY_BROWSER=off                  # disable the check
HERMES_TELEMETRY_BROWSER=/usr/bin/chromium    # or force a specific binary
HERMES_TELEMETRY_BROWSER_URL=https://...      # load this page instead

Run hermes-telemetry browser-check to print the discovery/launch result without sending an imprint.

Portmap check

A worker can be given its own subdomain — <agent>.fusenv.com — for inbound webhooks. When that is the case, every imprint verifies the mapping actually routes (any HTTP answer except 404 counts as mapped). Managed workers reach the phone gateway over the private tailnet instead, so the fleet runs with the check off.

HERMES_TELEMETRY_PORTMAP=off                     # disable the check (fleet default)
HERMES_TELEMETRY_PORTMAP=worker7.example.com     # check this hostname instead
HERMES_TELEMETRY_PORTMAP_DOMAIN=example.com      # keep <agent>. but change the domain

Version reporting

agent_info.version in each imprint is the version actually running. The reporter also asks the npm registry for the latest published hermes-telemetry and adds agent_info.latest / agent_info.upToDate, so the fleet dashboard can show which workers still run an old release.

HERMES_TELEMETRY_REGISTRY=off                            # skip the lookup
HERMES_TELEMETRY_REGISTRY=https://registry.example.com   # private mirror

Surviving reboots

The daemon does not install itself as a system service. Add one line to cron if you want it back after a reboot:

@reboot /usr/bin/env hermes-telemetry start

Inside the managed fleet image this is unnecessary: s6 supervises the reporter and relaunches npx hermes-telemetry@latest every 24 hours.

License

MIT