Skip to content
Guides
/
/
Hermes
Last updated

Hermes Integration

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

Overview

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:

HookTypeDescription
pre_tool_callBlockingTool execution requests before they run — can deny on policy violation
post_tool_callObservationTool execution results, errors, and duration after completion
pre_llm_callObservationPrompt and conversation context before the model call
post_llm_callObservationAssistant reply and reasoning after the model call
pre_gateway_dispatchObservationOutbound gateway messages (channel, recipient) before dispatch
pre_approval_requestObservationApproval requests before they are raised
post_approval_responseObservationApproval decisions after they are made
subagent_stopObservationSubagent termination
on_session_startObservationSession initialization and context
on_session_endObservationSession termination
on_session_finalizeObservationSession finalization and summary
on_session_resetObservationSession reset

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.

Prerequisites

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)

Step 1: Generate a Plugin Token

  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.

Step 2: Install the Plugin

Install the published Capsule plugin into the same environment that runs Hermes:

pip install capsule-hermes

Hermes discovers the plugin automatically through its entry point — no manual module registration is required.

Step 3: Configure the Plugin

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

Set the endpoint and behavior flags in config.yaml:

plugins:
  entries:
    capsule:
      endpoint: "https://agents.capsule.security/v1/hermes/hooks/events"
      block_on_risk: true
      fail_open: true
      timeout_ms: 5000

Provide the token as an environment variable where Hermes runs so the secret never lands in a config file:

export CAPSULE_HERMES_TOKEN="<token from Step 1>"

Configuration Options

KeyEnv VariableTypeDefaultDescription
endpointCAPSULE_HERMES_ENDPOINTstring(required)Capsule Hermes hooks endpoint, e.g. https://agents.capsule.security/v1/hermes/hooks/events
tokenCAPSULE_HERMES_TOKENstring(required)JWT generated in Step 1, scoped to your tenant and environment
block_on_riskCAPSULE_HERMES_BLOCK_ON_RISKbooleantrueApply server block verdicts inline on pre_tool_call. Set to false to run in observe-only mode
fail_openCAPSULE_HERMES_FAIL_OPENbooleantrueWhen Capsule is unreachable or returns an error, allow the agent to proceed. Set to false to fail closed
timeout_msCAPSULE_HERMES_TIMEOUT_MSnumber5000Per-request timeout in milliseconds
user—string$USERUser identifier sent on every event

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

Token Storage

Never commit the JWT to version control. Recommended approaches:

  • Read the token from 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

Step 4: Restart Hermes

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.

Step 5: Verify the Installation

  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.

Troubleshooting

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 configuration is set — the plugin logs capsule_hermes: not registering hooks and skips registration if the endpoint or token is missing.

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

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

  5. 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.

  6. Contact Capsule Security support if issues persist.

Security Considerations

The Capsule plugin runs in-process inside Hermes and observes every tool call, model call, gateway message, and approval. 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 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.

Support

For help with this integration:

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

References

Previous page
Next page