Hermes Integration

Connect the Hermes autonomous AI agent runtime to Capsule Security for complete visibility into agent activity - tool calls, model calls, approvals, skills, and session lifecycle - with inline blocking on policy-violating tool executions.

This integration uses a Capsule plugin that runs in-process inside the Hermes runtime. The plugin registers handlers on Hermes' hook system, forwards every hook event to your Capsule tenant over HTTPS, and applies the server's verdict on the hooks that support inline blocking.

Hermes is operator-deployed - you run the runtime in your own infrastructure, so there is no SaaS install. The only thing exchanged at install time is a signed token that scopes the plugin to your tenant and environment.

The following hooks are configured:

The blocking hook awaits Capsule's verdict and returns a block directive to Hermes when the server denies the action. Observation hooks dispatch fire-and-forget so telemetry never stalls the agent.

On the first hook of each session, the plugin also sends the files Hermes loads into the agent's context, so Capsule can detect instruction and memory poisoning and inventory the agent's skills:

The Hermes home is ~/.hermes (%LOCALAPPDATA%\hermes on Windows) unless HERMES_HOME or a profile points elsewhere.

Before you begin, ensure you have:

• A running Hermes runtime (Python 3.10 or later)
• A Capsule Security account with admin access
• Network access from the host running Hermes to your Capsule agentsecurity endpoint (e.g. https://agents.capsule.security)

1. Log in to the Capsule Security portal.

2. Navigate to Integrations and locate Hermes.

3. Click Install - Capsule generates a JWT scoped to your tenant and Hermes environment. The token contains the tenant and environment claims required by the agentsecurity endpoint; treat it as a secret.

4. Copy the generated endpoint and token. You will reference them from your Hermes configuration in the next steps.

Hermes plugins are opt-in: an installed plugin stays inactive until it is listed in plugins.enabled, and Hermes does not log that it skipped it.

Hermes loads plugin code only from an environment it builds itself, so a plain pip install is invisible to it. Create a plugin directory in the Hermes home that declares the published capsule-hermes package as a dependency, then enable it:

D="${HERMES_HOME:-$HOME/.hermes}/plugins/capsule"
mkdir -p "$D"
cat > "$D/plugin.yaml" <<'EOF'
name: capsule
description: Capsule Security policy enforcement and audit for Hermes
python_dependencies:
  - "capsule-hermes>=0.5,<1"
EOF
echo 'from capsule_hermes import register' > "$D/__init__.py"
hermes plugins disable capsule
hermes plugins enable capsule

hermes plugins enable installs capsule-hermes from PyPI into the Hermes environment. The disable before it makes that happen even when capsule is already enabled, for example from an earlier pip install.

On Windows, run this in PowerShell instead:

$H = if ($env:HERMES_HOME) { $env:HERMES_HOME } else { "$env:LOCALAPPDATA\hermes" }
$D = New-Item -ItemType Directory -Force -Path "$H\plugins\capsule"
Set-Content -Path "$D\plugin.yaml" -Value @'
name: capsule
description: Capsule Security policy enforcement and audit for Hermes
python_dependencies:
  - "capsule-hermes>=0.5,<1"
'@
Set-Content -Path "$D\__init__.py" -Value 'from capsule_hermes import register'
hermes plugins disable capsule
hermes plugins enable capsule

To upgrade to the latest release, rerun hermes plugins disable capsule and then hermes plugins enable capsule.

Install the package into the same Python environment that runs Hermes, then enable it:

pip install capsule-hermes
hermes plugins enable capsule

Run hermes plugins list to confirm capsule is enabled.

The plugin reads its configuration from environment variables (highest precedence) or from the plugins.entries.capsule block in your Hermes config.yaml.

Add the endpoint and token to ~/.hermes/.env, the file Hermes loads its secrets from at startup:

CAPSULE_HERMES_ENDPOINT=https://agents.capsule.security/v1/hermes/hooks/events
CAPSULE_HERMES_TOKEN=<token from Step 1>

To change the behavior flags, add them to config.yaml, merging into the existing plugins: section rather than adding a second one:

plugins:
  entries:
    capsule:
      block_on_risk: true
      fail_open: true
      timeout_ms: 5000

Environment variables take precedence over the config.yaml block, so the same configuration works in CI and containerized deployments without editing the file.

Never commit the JWT to version control. Recommended approaches:

• Keep the token in ~/.hermes/.env or the CAPSULE_HERMES_TOKEN environment variable
• Source it from your secret manager (1Password, AWS Secrets Manager, HashiCorp Vault) at runtime
• Deliver it through the same channel that distributes the rest of your Hermes deployment configuration

For the plugin to take effect, restart the Hermes runtime with the updated configuration. On startup the plugin logs the following when it registers successfully:

capsule_hermes: registered (endpoint=https://agents.capsule.security/v1/hermes/hooks/events, block_on_risk=True, fail_open=True)

If the endpoint or token is missing, the plugin logs capsule_hermes: not registering hooks and stays inert rather than failing the runtime.

1. Start a new Hermes session and run a task that executes a tool to generate activity.

2. Log in to the Capsule Security portal.

3. Navigate to Inventory > Agents and confirm your Hermes agent appears.

4. Click on the agent and review the audit logs to verify events are captured:

   • Session start event
   • Tool execution (pre/post tool call)
   • Model call activity

5. To view the full conversation, navigate to Observability and filter by Activity Type - Session.

If events are not appearing:

1. Verify the endpoint is reachable from the host running Hermes:

   curl -sS -o /dev/null -w "%{http_code}\n" https://agents.capsule.security/v1/hermes/hooks/

2. Verify the plugin is enabled - run hermes plugins list. If capsule is not enabled, run hermes plugins enable capsule and restart Hermes. On Hermes 0.21.6 or later, a capsule missing from the list means the plugin directory from Step 2 is missing; hermes plugins doctor capsule checks the directory, the package import, and hook registration.

3. Verify the configuration is set - the plugin logs capsule_hermes: not registering hooks and skips registration if the endpoint or token is missing.

4. Check for timeouts - if your network has high latency to the Capsule endpoint, increase timeout_ms or confirm fail_open is set appropriately.

5. Confirm the plugin is loaded - look for the capsule_hermes: registered line in the Hermes startup logs.

6. Inspect the logs for per-request failures. The plugin logs structured warnings with a correlation_id when a request fails or the server returns a non-2xx response.

7. Contact Capsule Security support if issues persist.

The Capsule plugin runs in-process inside Hermes and observes every tool call, model call, approval, and the instruction, memory, and skill files listed above. Before deploying:

1. Protect the JWT - anyone with the token can post events on behalf of your tenant. Rotate it through the portal if it is exposed.
2. Choose fail_open deliberately - fail_open: true (the default) prioritizes agent availability and lets actions through when Capsule is unreachable; fail_open: false prioritizes policy enforcement and blocks tool execution when Capsule cannot be reached.
3. Pin a plugin version in production (for example capsule-hermes==0.5.0 in plugin.yaml) and review changelogs before upgrading.
4. Use TLS-only endpoints. The plugin sends a Bearer token on every request - never configure an http:// endpoint outside local development.

For help with this integration:

• Email: support@capsule.security
• Include: Your organization ID, integration status, plugin version, and any error messages

• Hermes
• Capsule Hermes Plugin on PyPI