@agentworkspaceos/hermes

AgentOS connector CLI for pairing a Hermes runtime with an AgentOS workspace.

Usage

Run this command from the machine where Hermes is installed. This can be a laptop or a VPS:

npx --yes @agentworkspaceos/hermes@latest connect \
  --mode plugin \
  --agent auto \
  --pair AGOS-XXXX-XXXX \
  --agentos-url http://127.0.0.1:3002

The connector sends safe runtime metadata and heartbeat lease status to AgentOS, then opens an outbound task relay so AgentOS can deliver work without calling your laptop, LAN IP, or VPS port directly. If AgentOS advertises an edge relay URL, the CLI keeps the long-lived event stream on that relay and uses short AgentOS API calls to claim tasks and post results. Polling stays enabled as a compatibility fallback. When AgentOS queues the connection test, the connector receives it outbound, sends it to the local Hermes gateway, and reports the result back. Secrets stay on the machine running Hermes.

Use --agent auto to scan known local runtimes and advertise the installed ones through the AgentOS local hub. Supported built-in keys are hermes, claude-code, codex, and openclaw; repeat the flag or comma-separate values to register a specific set.

If the dashboard is opened through a browser-only or Cloudflare-protected URL, keep --agentos-url pointed at the direct AgentOS API base URL, configure an AgentOS Hermes relay URL, or use --no-relay so the connector uses polling only.

When --hermes-url is omitted, the CLI probes common local Hermes gateway ports (8642 through 8645) and falls back to http://127.0.0.1:8642. Use --hermes-url when Hermes is running on an unusual local port or a reachable remote gateway. --dashboard-url is optional and can be omitted when the Hermes dashboard is not running.

Background Service

On macOS, install the connector as a LaunchAgent so it keeps running after the terminal closes and restarts if it exits:

npx --yes @agentworkspaceos/hermes@latest service install \
  --mode plugin \
  --agent auto \
  --pair AGOS-XXXX-XXXX \
  --agentos-url https://agentos-relay.rewardsbunny.com \
  --relay-url https://agentos-relay.rewardsbunny.com

Logs are written to ~/.agentos/hermes/logs/connector.log. Remove the service with:

npx --yes @agentworkspaceos/hermes@latest service uninstall

If the AgentOS page keeps waiting for a heartbeat after install, check launchd and the connector logs:

npx --yes @agentworkspaceos/hermes@latest service status
tail -n 80 ~/.agentos/hermes/logs/connector.log ~/.agentos/hermes/logs/connector.err.log

service status also reports the local AgentOS URL, Hermes URL, pairing code, connector token presence, and queued result count. Use --no-launchctl to print those diagnostics without inspecting macOS launchd.

You can also verify the pairing endpoint in the foreground with the same command shape plus connect --once:

npx --yes @agentworkspaceos/hermes@latest connect \
  --mode plugin \
  --agent auto \
  --pair AGOS-XXXX-XXXX \
  --agentos-url https://agentos-relay.rewardsbunny.com \
  --relay-url https://agentos-relay.rewardsbunny.com \
  --once

For a VPS, run the same service install command on the VPS. The Hermes gateway can stay bound to 127.0.0.1:8642 because the connector keeps an outbound AgentOS relay open and forwards tasks locally.

Options

agentos-hermes connect --pair <code> [options]

--agentos-url <url>    AgentOS API base URL
--agent <name>         Local hub runtime: auto, hermes, claude-code, codex, openclaw
--relay-url <url>      Optional AgentOS Hermes relay URL
--hermes-url <url>     Local Hermes gateway URL; omitted means auto-detect local Hermes
--dashboard-url <url>  Optional Hermes dashboard URL
--mode <mode>          plugin, sidecar, or direct-url
--config-dir <path>    Local config directory
--hermes-command <cmd> Hermes CLI executable
--interval-ms <ms>     Heartbeat interval
--task-poll-interval-ms <ms> AgentOS task polling interval
--task-timeout-ms <ms> Max time to wait for a Hermes task result
--no-relay             Disable outbound task relay and use polling only
--skip-inventory       Send basic heartbeat metadata only
--once                 Send one heartbeat and exit

agentos-hermes service install --pair <code> --agentos-url <url> [options]
agentos-hermes service uninstall [options]
agentos-hermes service status [--no-launchctl]

Publish

The package is configured for public scoped publishing:

npm login
npm publish --access public

You must own or have publish access to the @agentworkspaceos npm scope before publishing.