Skip to main content

ory-hermes

Ory Agent Security for Hermes Agent.

ory-hermes is a Hermes plugin. Hermes calls it before and after every tool call, so each call is authorized against Ory Permissions, audited, and tied to the user → agent identity. It is built on ory-argus.

Install

Install the package into the Python environment Hermes runs in, then enable the plugin:

pip install ory-hermes
hermes plugins enable ory-hermes

Hermes discovers the package through the hermes_agent.plugins entry point. Plugins are opt-in in Hermes: nothing is checked until ory-hermes is in plugins.enabled (hermes plugins enable adds it). Restart Hermes after enabling, and confirm with hermes plugins list.

If you cannot install packages into that environment, install it as a directory plugin instead. Create ~/.hermes/plugins/ory-hermes/ with two files and enable it the same way:

# plugin.yaml
name: ory-hermes
provides_hooks: [on_session_start, pre_tool_call, post_tool_call, subagent_start, on_session_end]
python_dependencies: ["ory-hermes>=1,<2"]
# __init__.py
from ory_hermes import register

The installed ory_hermes package directory also carries a plugin.yaml, so a copy of it works as a directory plugin when ory-argus is importable.

What it does

Hermes hook Ory behavior
on_session_start Starts user sign-in and agent identity in the background. It never waits and never blocks the session.
pre_tool_call Authorizes the call. Runs for built-in, plugin, and MCP tools, and for delegate_task.
post_tool_call Records tool.complete, or tool.fail when Hermes reports an error, a timeout, or a cancellation.
subagent_start Records the delegation to the child agent. Its tool calls are then checked in the delegating session.
on_session_end Flushes queued activity after each turn.

In enforce mode a denied tool is vetoed with Hermes' block directive, {"action": "block", "message": "..."}. The tool does not run and the model receives the reason. In observe mode the denial is recorded and the tool runs.

When the check itself fails, enforce mode denies on authorization, TLS, network, rate-limit, and server failures, and allows on not-found and other unknown failures. Observe mode never blocks.

Hermes blocks a tool when a pre_tool_call plugin raises or runs longer than plugins.hook_callback_timeout (30 seconds by default). The plugin therefore decides within 25 seconds and treats a check that takes longer as a network failure. The first tool call of a session waits up to 10 seconds for sign-in to finish and is then checked without it. To change either limit, or to pass your own client, register the plugin from a directory plugin:

# ~/.hermes/plugins/ory-hermes/__init__.py
from ory_hermes import OryHermesPlugin


def register(ctx):
    OryHermesPlugin(decision_timeout=50, session_start_wait=20).register(ctx)

Keep decision_timeout below Hermes' plugins.hook_callback_timeout.

MCP tools

Hermes registers MCP tools as mcp__<server>__<tool>. Those calls are checked as McpServer:<server> and McpTool:<server>:<tool> instead of plain tools.

The server is read from the tool's mcp-<server> toolset in Hermes' registry, which keeps the unsanitized server name. If that is unavailable, it comes from the mcp_servers entry whose sanitized name prefixes the tool, and otherwise from the tool name itself. For a name Hermes shortened to 64 characters with a hash suffix, only the McpServer check applies. The server's URL host or launched package from mcp_servers is sent as a hashed fingerprint, so Agent Security matches the server to its catalog whatever it is named. URLs and arguments are not sent.

Wrapping your own callables

guard_callable, guard_function_map, and guard_tools wrap tool callables that your own code dispatches, for example in a custom embedding. A denied call raises OryDenialError before the tool body runs.

from ory_hermes import guard_function_map

tools = guard_function_map({"search": search, "fetch": fetch})

These wrappers do not protect Hermes Agent. Hermes dispatches tools through its registry and never reads a wrapped copy, so use the plugin for Hermes.

Limits

  • Hermes is not published as an installable Python package, so this package has no Hermes dependency and no real-SDK compatibility test. Its tests drive the hooks with the payloads Hermes sends, taken from the Hermes source.
  • Hermes tools are checked by tool name. Commands run through Hermes' terminal tool are not split into per-command shell checks.

Credentials come from the shared ~/.config/ory-agent-plugins/config.json, so a login performed by any other Ory harness plugin or SDK integration is reused here.

Metadata

Release files for ory-hermes 1.10.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ory-hermes 1.10.2
File Size Uploaded Provenance Actions
ory_hermes-1.10.2.tar.gz 23.4 kB Without provenance Details for ory_hermes-1.10.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ory-hermes 1.10.2
File Interpreter ABI Platform Actions
ory_hermes-1.10.2-py3-none-any.whl Python 3 none any Details for ory_hermes-1.10.2-py3-none-any.whl

Total release size: 39.7 kB

Release files / ory_hermes-1.10.2.tar.gz

Download URL ory_hermes-1.10.2.tar.gz
Size 23.4 kB
Tags Source
SHA-256 checksum
How to use checksums
d8233b0707723a8ea3a0ea7b449ce3bfb9f376fe16aac7249de5d485ebef85ff
BLAKE2b-256 checksum
How to use checksums
70f644e95172d9faea0436aeafa3cdd44a8e9be5c891a64be10a2ad2f402a9f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ory_hermes-1.10.2-py3-none-any.whl

Download URL ory_hermes-1.10.2-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fab41025fb3a52a305e2bcd93ae2025a360c9c0591b21c2f1f9f147a59d3bc54
BLAKE2b-256 checksum
How to use checksums
f5668a1c63287adc5803d93f2ccb938632f03d83f3d54d53ea91ea9f55635698
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ory-hermes 1.10.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page