Metadata-Version: 2.4
Name: capsule-hermes
Version: 0.4.1
Summary: Capsule plugin for Hermes — forwards hook events to the Capsule agentsecurity service for centralized policy enforcement and audit.
Project-URL: Homepage, https://github.com/capsulesecurity
Project-URL: Documentation, https://docs.capsulesecurity.io/guides/hermes
Author: Capsule Security
License: Capsule Security Commercial License
        
        Copyright (c) Capsule Security, Inc. All rights reserved.
        
        This software is licensed, not sold, and is made available solely to customers
        of Capsule Security, Inc. ("Capsule") under the terms of an active commercial
        agreement (the "Subscription Agreement") between the customer and Capsule.
        
        Subject to the Subscription Agreement, Capsule grants the customer a
        non-exclusive, non-transferable, non-sublicensable, revocable license to install
        and run this software in connection with the customer's authorized use of the
        Capsule platform, solely for the customer's internal business operations.
        
        Except as expressly permitted by the Subscription Agreement, you may not:
          (a) copy, modify, or create derivative works of the software;
          (b) reverse engineer, decompile, or disassemble the software;
          (c) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
              software to any third party;
          (d) remove or alter any proprietary notices contained in the software; or
          (e) use the software except in connection with an active Subscription
              Agreement.
        
        Without a valid Subscription Agreement with Capsule, no rights are granted to
        use this software. Unauthorized use is prohibited.
        
        THE SOFTWARE IS PROVIDED "AS IS" AND CAPSULE DISCLAIMS ALL WARRANTIES, EXPRESS
        OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. CAPSULE SHALL NOT BE
        LIABLE FOR ANY DAMAGES ARISING FROM OR RELATING TO USE OF THE SOFTWARE EXCEPT
        AS EXPRESSLY SET FORTH IN THE SUBSCRIPTION AGREEMENT.
        
        For licensing inquiries, contact: sales@capsulesecurity.io
License-File: LICENSE
Keywords: agent-security,capsule,hermes,hermes-plugin,policy,security
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# capsule-hermes

Capsule plugin for the [Hermes](https://nousresearch.com/hermes) autonomous AI agent runtime. Forwards Hermes hook events to the Capsule `agentsecurity` service for centralized policy enforcement and audit.

## Install

```bash
pip install capsule-hermes
```

## Configure

Register the plugin in your Hermes runtime config (e.g. `hermes.yaml`):

```yaml
plugins:
  - module: capsule_hermes
    config:
      endpoint: "https://agents.capsulesecurity.io/v1/hermes/hooks/events"
      token: ${CAPSULE_HERMES_TOKEN}
```

The `endpoint` and `token` values are issued by Capsule when you install the Hermes integration in the Capsule portal (**Integrations → Hermes**).

### Optional config

| Key             | Default | Description                                                                                              |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `block_on_risk` | `true`  | Apply server `block` verdicts. Set to `false` to run the plugin in observe-only mode.                    |
| `fail_open`     | `true`  | Allow the event through if Capsule is unreachable or returns a non-2xx response. Set to `false` to fail closed. |
| `timeout_ms`    | `5000`  | Per-request HTTP timeout in milliseconds.                                                                 |

## Hooks covered

The plugin registers handlers for the Hermes runtime hooks Capsule supports:

- **Blocking:** `pre_tool_call`, `pre_llm_call`, `pre_gateway_dispatch`, `pre_approval_request`
- **Observation:** `post_tool_call`, `post_llm_call`, `post_approval_response`, `subagent_stop`, `on_session_start`, `on_session_end`, `on_session_finalize`, `on_session_reset`

Blocking hooks await Capsule's verdict and return `{"action": "block", "message": ...}` to Hermes when the server denies the action. Observation hooks dispatch fire-and-forget so telemetry never stalls the agent.

## License

Apache-2.0.
