Atbash Hermes Plugin

Atbash guardrail plugin for Hermes Agent using the official Python SDK (atbash-sdk).

The plugin registers a Hermes pre_tool_call hook and asks Atbash for a verdict before a Hermes tool runs. If Atbash returns a blocking decision, the tool call is stopped before execution.

What It Does

• Intercepts Hermes tool calls through pre_tool_call.
• Sends the tool name, arguments, command-like payload, session metadata, and inferred action class to Atbash.
• Blocks tool execution on BLOCK, DENY, REJECT, DISALLOW, or HOLD.
• Persists learned Hermes tool classifications across sessions.

Install

Install the plugin into the same Python environment that runs Hermes. This prerelease requires Python 3.10 through 3.12, matching atbash-sdk==0.7.1.dev0.

pip install --pre atbash-hermes-plugin==0.4.13.dev0

If Hermes is installed in a virtual environment, use that environment's Python:

/path/to/hermes/venv/bin/python -m pip install --pre atbash-hermes-plugin==0.4.13.dev0

Maintainers: releases use clean staged source, live PyPI monotonic checks, and Trusted Publishing. See the release process.

Configure Atbash

The plugin needs an Atbash agent key. Configure either ATBASH_KEY_PATH or ATBASH_AGENT_PRIVKEY.

Recommended:

ATBASH_KEY_PATH=$HOME/.config/atbash/guard-client-key

Alternative:

ATBASH_AGENT_PRIVKEY='{"pubkey":"...","privkey":"..."}'

Where To Set Environment Variables

Hermes commonly loads environment variables from ~/.hermes/.env.

Create or edit that file:

nano ~/.hermes/.env

Add:

ATBASH_KEY_PATH=$HOME/.config/atbash/guard-client-key
ATBASH_ENFORCE_DECISION=true
ATBASH_DEBUG=false
ATBASH_ORG_NAME=your-org-name

Restart Hermes after changing .env.

For a one-off terminal session, you can also export variables before starting Hermes:

export ATBASH_KEY_PATH="$HOME/.config/atbash/guard-client-key"
export ATBASH_ENFORCE_DECISION=true
export ATBASH_DEBUG=false
hermes

Optional Settings

# Override the Atbash API endpoint.
ATBASH_ENDPOINT=https://api.atbash.io

# Set to self-hosted when using your own judge endpoint. Self-hosted judges
# require ATBASH_JUDGE_VERIFY_PUBKEY so the SDK can verify signed responses.
ATBASH_JUDGE_ENDPOINT_POLICY=default
ATBASH_JUDGE_VERIFY_PUBKEY=

# Fail closed when Atbash cannot be reached. Default: true.
ATBASH_ENFORCE_DECISION=true

# Emit verbose plugin logs. Default: false.
ATBASH_DEBUG=false

# Resolve the Atbash organization subscription/network. This lets the SDK
# choose the public or private chain for that org.
ATBASH_ORG_NAME=your-org-name

# Override where learned Hermes tool classifications are saved.
ATBASH_TOOL_MAP_PATH=$HOME/.config/atbash/hermes-tool-map.json

# Override where the persistent memory-tamper hash store is saved.
# Default: ~/.config/atbash/hermes-memory-hashes.json
ATBASH_MEMORY_HASH_PATH=$HOME/.config/atbash/hermes-memory-hashes.json

# Hermes provider and model — informational, passed through to Atbash context.
HERMES_PROVIDER=
HERMES_MODEL=

Telemetry

The plugin initializes the Atbash Python SDK OpenTelemetry metrics with source="plugin:hermes", matching the pattern used by the OpenClaw plugin. Telemetry is best-effort and never blocks guard registration or tool execution.

The Python SDK telemetry opt-out is file-based. To disable telemetry, create:

mkdir -p ~/.config/atbash
printf '{"enabled": false}\n' > ~/.config/atbash/telemetry.json

Enable Or Check The Plugin

Hermes should discover installed Python packages that expose the hermes_agent.plugins entry point.

Check whether Hermes sees the plugin:

hermes plugins list | grep atbash

If needed, enable it:

hermes plugins enable atbash-hermes-plugin

Verify It Is Working

Start Hermes and ask it to do something that uses a tool, such as creating a file or opening a website.

In another terminal, watch the Hermes log:

tail -f ~/.hermes/logs/agent.log

With ATBASH_DEBUG=true, you should see lines similar to:

[atbash-hermes-plugin] registered pre_tool_call hook mode=fail-closed
Atbash pre_tool_call enter tool=...
Atbash verdict tool=... verdict=ALLOW reason=...

If Atbash blocks a tool call, Hermes receives a blocking response before the tool executes.

Docker

When running Hermes in Docker, mount your Hermes data directory and put the Atbash key inside the mounted volume.

Example host layout:

~/.hermes/
  .env
  atbash/
    guard-client-key

Example ~/.hermes/.env for Docker:

ATBASH_KEY_PATH=/opt/data/atbash/guard-client-key
ATBASH_ENFORCE_DECISION=true
ATBASH_DEBUG=false
ATBASH_ORG_NAME=your-org-name

Run Hermes:

docker run --rm -it \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

You can also pass variables directly:

docker run --rm -it \
  -v ~/.hermes:/opt/data \
  -e ATBASH_KEY_PATH=/opt/data/atbash/guard-client-key \
  -e ATBASH_ENFORCE_DECISION=true \
  -e ATBASH_DEBUG=false \
  -e ATBASH_ORG_NAME=your-org-name \
  nousresearch/hermes-agent

Tool Classification

Hermes tool names can vary by version, installed plugins, and enabled skills. The plugin ships with defaults for common tools and learns unseen tool names at runtime.

Learned mappings are saved to:

~/.config/atbash/hermes-tool-map.json

Set ATBASH_TOOL_MAP_PATH to override the location. The file persists across Hermes sessions.

Verdict Behavior

• ALLOW with allow is True: the tool proceeds. A missing allow flag is denied.
• HOLD: the tool is blocked with a review message.
• BLOCK, DENY, REJECT, DISALLOW: the tool is blocked.
• Atbash API error:
  • ATBASH_ENFORCE_DECISION=true: fail closed and block.
  • ATBASH_ENFORCE_DECISION=false: fail open and allow.
• Memory writes (MEMORY.md, CLAUDE.md, memory/ paths) with No verdict: allowed and recorded as the new tamper baseline only when the judge marks the response as the AUDIT tier (status: "logged"). Any other missing verdict — empty body, truncated payload, a proxy error served as 200, a compromised judge — is blocked under ATBASH_ENFORCE_DECISION=true; under false the write proceeds but is never recorded as the baseline, because it was not judged.

Atbash ships fail-closed on every tier. Setting ATBASH_ENFORCE_DECISION=false inverts that for this agent: a judge outage becomes a silent allow, and the governance layer stops governing for as long as it lasts. That is supported, but record a written risk acceptance in the deployment's security summary before turning it off, so the trade-off is auditable after an incident rather than discovered during one. See decision 0003 (fail-closed default) in the dashboard repo.

For HOLD, the user-facing block message is:

Action held for operator review. The agent will not be jailed — please approve or reject this request from the Atbash dashboard, then ask the agent to try again.
Reason: <original reason from judge>
Tool Call ID: <held judgment id, when provided by the SDK>

After dashboard approval or rejection, the SDK can query held-action status with the judgment ID. The Hermes plugin blocks the original tool call and asks the user to retry after review, rather than automatically re-running the action.

Troubleshooting

If Hermes does not show the plugin:

hermes plugins list | grep atbash
python -m pip show atbash-hermes-plugin

Make sure the package was installed into the same Python environment that runs Hermes.

If Atbash verdicts are not appearing in logs:

ATBASH_DEBUG=true

Then restart Hermes and watch:

tail -f ~/.hermes/logs/agent.log

If the plugin blocks everything with an unavailable-key or authentication error, check:

echo "$ATBASH_KEY_PATH"
test -f "$ATBASH_KEY_PATH" && echo "key file exists"

If using Docker, remember that paths inside the container are different from host paths. Prefer /opt/data/... paths for mounted Hermes data.