Getting started

Requirements

• A working Hermes Agent install (hermes chat -q "hi" works).
• uv for installing AgentsFence into Hermes’ Python environment. AgentsFence depends only on pydantic and PyYAML.

1. Install the plugin

Install AgentsFence 0.2.0a3 from PyPI into Hermes’ Python environment:

uv pip install --python ~/.hermes/hermes-agent/venv/bin/python 'agentsfence==0.2.0a3'

The exact version keeps friends on the tested alpha release. PyPI hosts both a wheel and a source distribution; the source repositories remain private during friend testing. Invited repository collaborators may instead use hermes plugins install knightsrule/agentsfence after GitHub authentication.

2. Enable it

Hermes plugins are opt-in. Nothing loads until it’s listed in plugins.enabled:

hermes plugins enable agentsfence

If you use Hermes profiles, enable it in each one (hermes -p work plugins enable agentsfence). Each profile keeps its own AgentsFence state.

Safe mode turns the fence off

HERMES_SAFE_MODE=1 makes Hermes skip every plugin, including AgentsFence.

3. Choose a policy compiler

The compiler runs at task start and again when a later message could change authority. See Choosing a compiler for the trade-offs.

anthropic/claude-haiku-4.5

echo 'OPENROUTER_API_KEY=sk-or-...' >> ~/.hermes/.env

# Optional: this model compiled the alpha self-tests quickly in our setup
echo 'AGENTSFENCE_COMPILER_MODEL=openai/gpt-4.1-mini' >> ~/.hermes/.env

# …or reuse your Hermes model (no extra key)
echo 'AGENTSFENCE_COMPILER_PROVIDER=hermes' >> ~/.hermes/.env

# …or fully offline, deterministic rules
echo 'AGENTSFENCE_COMPILER_PROVIDER=rules' >> ~/.hermes/.env

If the compiler can’t be reached

If the compiler is unavailable (missing key, network down, invalid output), the task gets a read-only fallback policy, and any explicit prohibitions in your request still apply. The fallback always errs toward less authority.

4. Verify

The package also installs an optional agentsfence command-line tool in Hermes’ environment:

~/.hermes/hermes-agent/venv/bin/agentsfence doctor

doctor checks that the plugin is enabled and that the compiler has what it needs. Then start Hermes as usual:

hermes chat

Inside a CLI session:

• /fence shows the active task policy.
• /fence audit shows the most recent decisions.

In gateway chats (Telegram, Slack, …) /fence is disabled; use agentsfence audit on the host.

To see it work on your own setup, run the before-and-after self-test. Then read Using AgentsFence with Hermes for how profiles, sessions, the gateway, subagents, cron and approval modes interact with the fence, and browse the scenario cookbook.

What you’ll notice

• Nothing, most of the time. Reads, searches and anything you asked for go through without prompts.
• An approval prompt when the agent wants to do something consequential you didn’t ask for. Approving grants only that exact action, for example one email to one recipient.
• A block when the action is something you forbade (“don’t send”), or is destructive, financial or a permission change you didn’t authorize. The agent is told why and asked not to find a workaround.

Uninstall

hermes plugins disable agentsfence
uv pip uninstall --python ~/.hermes/hermes-agent/venv/bin/python agentsfence

Policies and the audit log are stored in ~/.hermes/agentsfence/. Delete that directory to remove them.