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'
terminaltool 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.