# Hermes Integration

Connect the [Hermes](https://nousresearch.com/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:

| Hook | Type | Description |
|  --- | --- | --- |
| **pre_tool_call** | Blocking | Tool execution requests before they run — can deny on policy violation |
| **post_tool_call** | Observation | Tool execution results, errors, and duration after completion |
| **pre_llm_call** | Observation | Prompt and conversation context before the model call |
| **post_llm_call** | Observation | Assistant reply and reasoning after the model call |
| **pre_gateway_dispatch** | Observation | Outbound gateway messages (channel, recipient) before dispatch |
| **pre_approval_request** | Observation | Approval requests before they are raised |
| **post_approval_response** | Observation | Approval decisions after they are made |
| **subagent_stop** | Observation | Subagent termination |
| **on_session_start** | Observation | Session initialization and context |
| **on_session_end** | Observation | Session termination |
| **on_session_finalize** | Observation | Session finalization and summary |
| **on_session_reset** | Observation | Session 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:


```bash
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`:


```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:


```bash
export CAPSULE_HERMES_TOKEN="<token from Step 1>"
```

### Configuration Options

| Key | Env Variable | Type | Default | Description |
|  --- | --- | --- | --- | --- |
| `endpoint` | `CAPSULE_HERMES_ENDPOINT` | `string` | *(required)* | Capsule Hermes hooks endpoint, e.g. `https://agents.capsule.security/v1/hermes/hooks/events` |
| `token` | `CAPSULE_HERMES_TOKEN` | `string` | *(required)* | JWT generated in Step 1, scoped to your tenant and environment |
| `block_on_risk` | `CAPSULE_HERMES_BLOCK_ON_RISK` | `boolean` | `true` | Apply server `block` verdicts inline on `pre_tool_call`. Set to `false` to run in observe-only mode |
| `fail_open` | `CAPSULE_HERMES_FAIL_OPEN` | `boolean` | `true` | When Capsule is unreachable or returns an error, allow the agent to proceed. Set to `false` to fail closed |
| `timeout_ms` | `CAPSULE_HERMES_TIMEOUT_MS` | `number` | `5000` | Per-request timeout in milliseconds |
| `user` | — | `string` | `$USER` | User 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:

```bash
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

- [Hermes](https://nousresearch.com/hermes)
- [Capsule Hermes Plugin on PyPI](https://pypi.org/project/capsule-hermes/)