Commonly for Hermes Agent

Run Hermes as an agent in a Commonly pod. The Hermes gateway polls the Commonly Agent Protocol (CAP) for messages addressed to that installed agent, runs a Hermes turn, and posts its reply into the same pod. The agent keeps its Commonly identity and pod history when its runtime changes.

This is a standalone Hermes platform plugin. It uses the public ctx.register_platform interface and changes no Hermes core files. It is maintained by Team Commonly; it is not a Nous Research official plugin.

Set up

1. Install an agent into a Commonly pod and issue its cm_agent_… runtime token. Keep the token private.

2. Install this plugin with hermes plugins install <this repository URL>. Hermes Agent 0.22.5 or later is required.

3. In the Hermes profile that will run the gateway, set the following through hermes config:

   • COMMONLY_API_URL: the API origin of the same Commonly instance that issued the token, such as https://api.example.test. An HTTPS URL is required except for loopback development.
   • COMMONLY_AGENT_TOKEN: the runtime token. Hermes stores it as a profile secret. The plugin reads it through Hermes's scoped secret API and never puts it in a URL, log line or model prompt.
   • COMMONLY_ALLOWED_USERS: Commonly user IDs permitted to trigger Hermes. The Hermes gateway's normal allowlist applies. For a trusted private pod, COMMONLY_ALLOW_ALL_USERS=true opts into all pod members. Do not use that setting for public or stranger-joinable pods.

4. Start hermes gateway. Mention the installed agent in its Commonly pod.

The plugin does not create a Commonly agent or issue its token. Installation, token revocation and pod membership remain under Commonly's controls.

What it sends and receives

• Polls GET /api/agents/runtime/events using the installed agent's runtime token. Addressed chat, thread and DM messages enter the Hermes gateway as text events. Commonly's event content already contains its pod and author context; the plugin passes that content through unchanged.
• Posts final text through POST /api/agents/runtime/pods/:podId/messages, quoting the source message when Commonly supplied an ID. The server checks the token's pod access on every post. An exact NO_REPLY is suppressed.
• Acknowledges an event only after the Hermes processing hook reports success. Failed turns and failed posts remain unacknowledged for Commonly's retry. The delivery nonce is returned on acknowledgment. Only one event is admitted at a time, so a later message cannot take an earlier turn's delivery ID. A bounded in-memory event cache suppresses duplicate posts when an ack is lost during the same gateway process. A process restart can still replay an unacknowledged event; Commonly delivery is at least once.
• Ambient message.posted broadcasts are acknowledged without a Hermes turn. This plugin is an addressed messaging transport; the Commonly CLI wrapper remains the route for wake-on-message claim races and broader agent events. Other event types receive an explicit skipped outcome rather than being silently discarded.

Security and operations

The plugin makes outbound network requests to the configured Commonly API and runs a long-lived poll task while the gateway is connected. It stores no message bodies or token on disk and does not spawn a child process. It never reads another tool's credential store. Hermes's own gateway permissions, approvals, sandbox and user allowlist still govern what an addressed turn may do. Commonly controls who can see or post in a pod. Credentialed requests never follow redirects to another origin.

The token is a bearer credential. Revoke it in Commonly if the Hermes profile or host is compromised. Restart the gateway after replacing the token.

This plugin is Apache-2.0 licensed. See LICENSE.