Metadata-Version: 2.4
Name: atbash-hermes-plugin
Version: 0.1.1
Summary: Atbash safety plugin for Hermes Agent
Author: atbash
License-Expression: LicenseRef-Atbash-Proprietary
Project-URL: Homepage, https://github.com/Atbash-Ai/atbash-hermes-plugin
Project-URL: Repository, https://github.com/Atbash-Ai/atbash-hermes-plugin
Keywords: atbash,hermes,hermes-agent,agent-safety,ai-safety,tool-guard,judge,policy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: atbash-sdk==0.1.3
Dynamic: license-file

# Atbash Hermes Plugin

Atbash guardrail plugin for [Hermes Agent](https://hermes-agent.nousresearch.com/)
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:

```bash
pip install atbash-hermes-plugin
```

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

```bash
/path/to/hermes/venv/bin/python -m pip install atbash-hermes-plugin
```

## Configure Atbash

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

Recommended:

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

Alternative:

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

## Where To Set Environment Variables

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

Create or edit that file:

```bash
nano ~/.hermes/.env
```

Add:

```bash
ATBASH_KEY_PATH=$HOME/.config/atbash/guard-client-key
ATBASH_ENFORCE_DECISION=true
ATBASH_DEBUG=false
```

Restart Hermes after changing `.env`.

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

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

## Optional Settings

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

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

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

# Override where learned Hermes tool classifications are saved.
ATBASH_TOOL_MAP_PATH=$HOME/.config/atbash/hermes-tool-map.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:

```bash
hermes plugins list | grep atbash
```

If needed, enable it:

```bash
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:

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

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

```text
[atbash-hermes-plugin] registered pre_tool_call hook
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:

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

Example `~/.hermes/.env` for Docker:

```bash
ATBASH_KEY_PATH=/opt/data/atbash/guard-client-key
ATBASH_ENFORCE_DECISION=true
ATBASH_DEBUG=false
```

Run Hermes:

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

You can also pass variables directly:

```bash
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 \
  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:

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

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

## Verdict Behavior

- `ALLOW`: the tool proceeds.
- `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.

## Troubleshooting

If Hermes does not show the plugin:

```bash
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:

```bash
ATBASH_DEBUG=true
```

Then restart Hermes and watch:

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

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

```bash
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.
