hermes-tenuo

Give each Hermes agent a signed, expiring permission slip. Nothing outside it runs.

See it without installing Hermes or talking to a model:

pip install hermes-tenuo
hermes-tenuo demo

A nightly job gets a permission slip: read /data/reports,
write /tmp/nightly, then stop. Nothing else runs.
No Hermes process, no API key.

== Cron ==
The job does the work. Then it tries to leave the slip.
  ALLOW  read_file  path=/data/reports/q3.csv
  ALLOW  write_file  path=/tmp/nightly/report.md
  DENY   read_file  path=/opt/private/payroll.csv
         Constraint 'path' not satisfied: value does not match constraint  ← /opt/private/payroll.csv is not under /data/reports
  DENY   terminal  command=ls
         Tool 'terminal' is not authorized  ← terminal is not on the slip
  (one second later)
  DENY   read_file  path=/data/reports/q3.csv
         Warrant has expired  ← the job window ended

That slip is a Tenuo warrant: signed, expiring, checked before
the handler runs. Same check, two more shapes:

== delegate_task ==
Same rule, after a handoff. The researcher was only granted web_search.
  [orchestrator] ALLOW  read_file  path=/data/input.csv
  [orchestrator] ALLOW  delegate_task  task=research q3  context=web_search only
  [researcher] ALLOW  web_search  query=AI papers 2026
  [researcher] DENY   write_file  path=/data/output/x.md
         Tool 'write_file' is not authorized  ← the researcher was not granted write_file

== Gateway ==
Same server, two slips.
  [analyst] ALLOW  read_file  path=/data/reports/q1.csv
  [analyst] DENY   write_file  path=/data/output/x.txt
         Tool 'write_file' is not authorized  ← write_file is not on the analyst's slip
  [viewer] ALLOW  read_file  path=/data/public/faq.md
  [viewer] DENY   read_file  path=/data/reports/q1.csv
         Constraint 'path' not satisfied: value does not match constraint  ← /data/reports is not on the viewer's slip

A Tenuo warrant is that slip. Each Hermes tool call is checked against it — tool name and arguments — before the handler runs. A delegate_task child only gets what the parent granted. A gateway user carries their own slip. Keys and decisions stay local.

The plugin returns the denial as the tool result, so the model sees why the handler never ran:

read_file  path=/opt/private/payroll.csv
Constraint 'path' not satisfied: value does not match constraint

For a recorded session with a real model and a planted prompt injection, see docs/walkthrough.md.

Install into Hermes

1. Install. hermes-tenuo is in the Hermes plugin catalog. On Hermes Agent 0.21.2 or newer, install it by catalog name to get the reviewed, pinned commit:

hermes plugins install hermes-tenuo
hermes plugins enable hermes-tenuo

Hermes 0.20 to 0.21.1 can't install by catalog name. Install from GitHub instead, which tracks the default branch rather than the reviewed pin:

hermes plugins install tenuo-ai/hermes-tenuo
hermes plugins enable hermes-tenuo

install asks for TENUO_WARRANT and TENUO_SIGNING_KEY. You mint those in the next step, so leave both empty for now. enable installs the tenuo dependency into the Hermes runtime.

If you manage the Hermes venv yourself, pip install hermes-tenuo into it instead. That also puts the hermes-tenuo command on your path, so you can drop the uvx prefix below. To run the latest unreleased code: pip install "git+https://github.com/tenuo-ai/hermes-tenuo.git".

Requires Hermes Agent 0.20 or newer. A nightly job loads the plugin through the plugin loader of upstream Hermes main using both install routes; the badge above is its latest result.

2. Mint a warrant. This generates a key pair and a warrant, and prints the exact config block to paste.

uvx hermes-tenuo mint --ttl 1h \
  --allow read_file:path=/data \
  --allow web_search

# ~/.hermes/config.yaml   (printed by the command above)
plugins:
  enabled:
    - hermes-tenuo
  entries:
    hermes-tenuo:
      warrant: <base64>            # or a path to a .warrant file
      trusted_root: <base64>       # the public key that signed it
      signing_key_env: TENUO_SIGNING_KEY

Put the printed TENUO_SIGNING_KEY in ~/.hermes/.env. Hermes reads that file when it starts. The uvx command below does not, so export the same value in this shell before the check:

export TENUO_SIGNING_KEY=<printed by mint>

3. Check it, then start Hermes. Run these in order:

hermes plugins doctor hermes-tenuo
uvx hermes-tenuo doctor
hermes

• hermes plugins doctor hermes-tenuo — Hermes loads the plugin and registers its hooks. This does not look at your warrant. If it cannot find the plugin, go back to step 1.
• uvx hermes-tenuo doctor — checks the config you pasted, the warrant, its expiry, and that the signing key matches the warrant holder. Fix anything it marks with ✗ before you start Hermes. This command runs outside Hermes, so it does not report the enforcement path.
• hermes — start the agent.

If you installed with pip install hermes-tenuo into the same environment Hermes uses, drop the uvx prefix. hermes-tenuo doctor then also prints which enforcement path is active.

Ask the agent to read /opt/private/payroll.csv. It gets the same denial as the tool result. Load skill_view("hermes-tenuo:tenuo-scope") to mint a warrant for a cron job, a delegate_task child, or a gateway session.

Scoping arguments

Each --allow names a tool and, optionally, constraints on its arguments. A tool with no constraints is allowed with any arguments.

A range only matches numbers: an amount sent as the string "40.00" is denied, so declare such arguments as numbers in the tool schema. Give both ends; 0..4000 also rules out negative amounts. Only a complete numeric MIN..MAX value is treated as a range, so values such as release..candidate continue to be exact strings. Tenuo ranges use IEEE-754 numbers; the CLI rejects non-finite bounds and values outside the safe integer range (-9007199254740991 to 9007199254740991).

Any argument the warrant does not name is unconstrained for that tool. The --ttl flag takes 30m, 1h, 7d, and so on (default 24h).

A number range is --allow checkout:amount=0..4000 (both ends, inclusive). For a case-insensitive path, or anything else the flag cannot express, mint in Python:

import base64, os
from tenuo import SigningKey, Warrant, Subpath, Pattern

control_key = SigningKey.generate()   # keep private; its public key is trusted_root
agent_key = SigningKey.generate()     # export its secret as TENUO_SIGNING_KEY

warrant = (
    Warrant.mint_builder()
    .holder(agent_key.public_key)
    .capability("read_file", path=Subpath("/data", case_sensitive=False))
    .capability("web_search", query=Pattern("acme*"))
    .ttl(3600)
    .mint(control_key)
)

path = os.path.expanduser("~/.hermes/tenuo/warrant")
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w") as f:
    f.write(base64.b64encode(warrant.to_bytes()).decode())

Point warrant: at that file. Set trusted_root to the base64 of control_key.public_key.to_bytes() and TENUO_SIGNING_KEY to the base64 of agent_key.secret_key_bytes().

What it unlocks

Runnable versions of the first three live in examples/.

See what your agent actually calls

Every decision is appended to a local JSONL audit log, on by default at ~/.hermes/tenuo/audit.jsonl (profile-aware under HERMES_HOME). No account needed.

hermes-tenuo audit --last 20          # one line per tool call
hermes-tenuo audit --denied           # only what the warrant blocked
hermes-tenuo audit --json | jq ...    # raw records

2026-09-12 10:00:00  ALLOW  read_file  path=/data/q3.md
2026-09-12 10:00:01  DENY   terminal  command=ls  — Tool 'terminal' is not authorized

Not sure what to allow yet? Set on_denial: log. Every call is still checked and recorded, but nothing is blocked. Run the agent, read the denied lines, tighten the warrant, then remove the line (the default is block).

plugins:
  entries:
    hermes-tenuo:
      warrant: ~/.hermes/tenuo/warrant
      trusted_root: <base64>
      on_denial: log

How it works

The decision itself runs in Tenuo's Rust core: signature, expiry, holder proof-of-possession, and every argument constraint. The plugin holds only the issuer's public key. It never sees the key that minted the warrant.

Denials are returned to the model as the tool result, so the agent can explain what it was not allowed to do. Raise the hermes_tenuo logger level to see the same lines as an operator.

Coverage

Hermes asks hermes-tenuo before each agent-loop tool handler runs (pre_tool_call). The coverage below describes current upstream Hermes main, exercised by the Upstream Hermes badge. Hermes 0.20 and later can load the plugin, but older releases may not route tool calls made inside execute_code through this hook. On an older or unverified build, do not grant execute_code to an agent or session whose isolation depends on hermes-tenuo.

On current Hermes main, that includes every tool call in the agent loop, the tools Hermes handles before its registry (todo, memory, session_search, delegate_task), and tool calls an execute_code script makes through Hermes, such as read_file or web_search. A caller that passes skip_pre_tool_call_hook=True has already been through this check.

Those execute_code calls are checked against the warrant in your config (TENUO_WARRANT, or plugins.entries.hermes-tenuo.warrant). Hermes does not send the gateway session id with them, so a warrant you attached with set_session_warrant is not the one applied. On a gateway, leave execute_code off a session warrant when that session must stay narrower than the config warrant.

Two things stay outside this check:

• Another plugin calling ctx.dispatch_tool(). That goes straight to registry.dispatch() and skips the hook. Only install plugins you trust alongside hermes-tenuo. A registry-level hook that closes this gap is proposed upstream in hermes-agent#32719. When Hermes provides it, hermes-tenuo uses it automatically.
• What an execute_code script runs on its own, such as subprocess.run(...). Use a container backend (Docker, Modal, Daytona) for that.

CLI

hermes-tenuo demo        # local allow/deny transcript (no Hermes process)
hermes-tenuo mint --allow TOOL[:ARG=VALUE,...] [--allow ...] [--ttl 1h] [--task ID] [--output full|yaml|env]
hermes-tenuo status      # what the plugin will load from config and env
hermes-tenuo verify      # signature (if trusted_root is set), expiry, capabilities
hermes-tenuo doctor      # end-to-end install check
hermes-tenuo audit [--last N] [--denied] [--json] [--path FILE]

After a catalog install these commands are not on your path. Prefix each one with uvx .

uvx hermes-tenuo doctor checks the config, warrant validity and expiry, and that the signing key matches the warrant holder. Export TENUO_SIGNING_KEY in that shell first, because uvx does not load ~/.hermes/.env. It does not report the enforcement path. Confirm Hermes loaded the plugin with hermes plugins doctor hermes-tenuo. Run both after every install.

Configuration reference

All keys live under plugins.entries.hermes-tenuo. Each has an environment variable equivalent.

Keep secret key material in env vars or a secrets manager, never in config.yaml.

Things to know

• Enabled but unconfigured is a no-op by default. Without a warrant, the plugin loads, logs a warning, and enforces nothing. doctor fails that check. Set require_warrant: true under plugins.entries.hermes-tenuo to block calls instead. This requires the plugin to load successfully; it cannot detect its own absence. With a warrant configured, on_denial continues to select observation (log) or enforcement (block).
• Multiplexed profiles. Under gateway.multiplex_profiles, TENUO_* values are read through Hermes get_secret, so put each profile's keys in that profile's .env. A secondary profile does not inherit the launch profile's credentials.
• Rotate by re-minting. The control key is not saved by mint. To change scope, mint a new warrant and replace the config values; the old warrant stops being accepted when you change trusted_root, or when its TTL ends.

Managed scope (fleet and multi-user)

Hermes overlays a root-owned /etc/hermes/config.yaml on every user's config. hermes-tenuo reads its keys through the same loader, so an administrator can pin the warrant and trust anchor for the whole fleet:

# /etc/hermes/config.yaml  (root-owned)
plugins:
  entries:
    hermes-tenuo:
      warrant: /etc/hermes/tenuo/fleet.warrant
      trusted_root: <base64>
      on_denial: block

Pin warrant, trusted_root, and on_denial. Leave signing_key_env to the environment. Override the managed directory with HERMES_MANAGED_DIR for containers or non-standard layouts.

Connecting a control plane (optional)

Everything above runs from files and environment variables on one machine. That is the right shape for one developer and a handful of agents. Once you run a fleet of Hermes agents, cron jobs, and gateway users, the hard part stops being the check itself and becomes operating the authority around it: who may mint production warrants, how keys rotate, how a bad warrant is pulled back before its TTL ends, and where you look when something was denied at 3 a.m. A Tenuo control plane takes that over.

When TENUO_CONNECT_TOKEN is set, the Tenuo SDK inside this plugin connects on its own and every allow and deny decision from every Hermes agent streams there, with nothing else to configure.

Install the cloud extra to also deliver each decision as a signed receipt:

pip install "hermes-tenuo[cloud]"

A receipt is signed by the agent's key, carries the proof-of-possession signature from the call it records, and links to the receipt before it, so a removed or edited entry shows up as a broken chain. Receipts are flushed when a session ends and when Hermes exits. Without the extra the plugin logs a warning and streams decisions without receipts. Delivering receipts never blocks or allows a call; the warrant check has already decided it.

On top of that stream the control plane gives you:

• Revocation before expiry. Pull a warrant, a key, or an agent the moment something looks wrong instead of waiting for the TTL. Revocation lists are published to every verifier.
• Central issuance and rotation. Mint per-job warrants from policy rather than by hand, and rotate root and holder keys on a schedule without touching each agent's environment.
• Human approval gates. Route calls to sensitive tools to a person, so the agent can proceed only with a signed approval.
• One searchable audit trail. Signed receipts from every agent, session, and profile in one place, instead of one audit.jsonl per machine.

Tenuo Cloud is the managed version of that control plane. See tenuo.ai for access, or the Tenuo repo for running your own.

License

Apache-2.0

Separate holder identity and warrant issuance

The operator does not need the holder's private key. Create the holder identity in the agent environment, keeping its private file there:

hermes-tenuo keygen --private-key holder.key --public-key holder.pub

Give only holder.pub to the operator. In the operator environment, create a separate issuer identity once and issue a scoped warrant:

hermes-tenuo keygen --private-key issuer.key --public-key issuer.pub
hermes-tenuo mint --issuer-key issuer.key --holder-public-key holder.pub \
  --ttl 20m --allow 'read_file:path=/data/reports' --out reports.warrant

Key and warrant files use base64 text. Outputs are created atomically with permissions 0600; existing files are never overwritten. Store issuer private keys outside the agent's accessible environment. No private key is printed by these commands. Explicit issuance completely ignores TENUO_SIGNING_KEY.

Give the agent reports.warrant and the trusted issuer.pub. Configure warrant: /absolute/path/reports.warrant and trusted_root to the base64 contents of issuer.pub in the plugin entry (the trusted-root setting does not read a file path). Load the holder private file into the agent's TENUO_SIGNING_KEY environment variable using your secret manager. Do not give the agent issuer.key.

Optional --session-id ID embeds a session binding in the signed warrant. It neither discovers a running session nor attaches the warrant to one. Ordinary static configuration still needs a restart after replacement. The original mint --allow ... quickstart remains available; it combines provisioning and issuance and prints a holder private key, so use it only in a trusted terminal.