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

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.0
File Size Uploaded Provenance Actions
ory_hermes-1.10.0.tar.gz 23.4 kB Without provenance Details for ory_hermes-1.10.0.tar.gz

Built distribution (wheel)

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

Total release size: 39.7 kB

Release files / ory_hermes-1.10.0.tar.gz

Download URL ory_hermes-1.10.0.tar.gz
Size 23.4 kB
Tags Source
SHA-256 checksum
How to use checksums
07baa19a0a577b7f93130b1b53195cb7291909551ab36ed435cf48cf1b72763d
BLAKE2b-256 checksum
How to use checksums
495ec05c5d9b108e27f348679f21216145da79a2829f36d4db040471b2dca2cb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.0-py3-none-any.whl

Download URL ory_hermes-1.10.0-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8ebbd7402d041ef7099e10baf7b1e0f87eba3047996b83cb09fb2427c3aa29f7
BLAKE2b-256 checksum
How to use checksums
1708c5f79150131d85566291427f38a08b33bdc6f3007942001cae6babcc4f7e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","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.0

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