agentguard-spend-hermes 0.1.4

AgentGuard Spend plugin for Hermes Agent (Nous Research). One-step install of local spend caps + signed audit logs for every Anthropic/OpenAI call your Hermes agent makes. No proxy, prompts never leave your machine.

agentguard-spend-hermes

One-step install of AgentGuard™ Spend into Hermes Agent (Nous Research).

Adds local spend caps + Ed25519-signed audit logs to every Anthropic and OpenAI call your Hermes agent makes. No proxy. No cloud component. Prompts and provider keys never leave your machine.

Built for Hermes's unattended-by-default workflow: cron jobs, sleep loops, multi-platform messaging bridges (Telegram, Discord, Slack, WhatsApp, Signal).

Install

# In the same virtualenv as Hermes
uv pip install agentguard-spend-hermes

That's it. Hermes's plugin manager auto-discovers the plugin via the hermes_agent.plugins entry point on next startup.

First-run auto-bootstrap

On first Hermes startup after install, the plugin:

1. Generates ~/.hermes/agentguard/private.key + public.key (Ed25519)
2. Writes a default policy.yaml ($5/day soft cap downgrades Opus → Sonnet, $20/day hard cap blocks, $2/min burst guard)
3. Monkey-patches the Anthropic and OpenAI client constructors so every LLM call is policy-checked + signed

You'll see in the Hermes log:

agentguard-spend: wrote default policy to ~/.hermes/agentguard/policy.yaml (locale: en-US)
agentguard-spend: generated signing keypair (private=..., public=...)
agentguard-spend: active (anthropic=True, openai=early, policy=...)

The policy file is localized to your system locale at first-write (en-US, es-419, or pt-BR).

When a cap fires

Downgrade (soft cap):

[hermes] anthropic.messages.create model=claude-opus-4-7
[agentguard] downgrade: claude-opus-4-7 -> claude-sonnet-4-6 (daily soft cap)
[hermes] continuing with sonnet

Block (hard cap):

[hermes] anthropic.messages.create model=claude-opus-4-7
[agentguard] block: hard daily ceiling exceeded
[hermes] AgentGuardBlockedError raised — agent halts this turn

Configure

Edit ~/.hermes/agentguard/policy.yaml and restart Hermes. Example:

id: hermes-default-v1
name: Hermes default caps
version: 1
effectiveFrom: "2026-01-01T00:00:00Z"
mode: enforce

scope:
  tenantId: hermes-personal

caps:
  - amountCents: 500     # $5/day soft cap
    window: per_day
    action: downgrade
    downgradeTo: claude-sonnet-4-6
  - amountCents: 2000    # $20/day hard cap
    window: per_day
    action: block
  - amountCents: 200     # $2/minute burst guard
    window: per_minute
    action: block

Disable temporarily

export AGENTGUARD_DISABLE=1   # plugin loads but does nothing

Per-platform spend caps

Set HERMES_AGENT_ID differently in each Hermes process to scope caps:

# Telegram bridge process
export HERMES_AGENT_ID=hermes-telegram

# Discord bridge process
export HERMES_AGENT_ID=hermes-discord

# Cron job
export HERMES_AGENT_ID=hermes-cron

Then write per-agent caps in policy.yaml:

caps:
  - amountCents: 1000
    window: per_day
    scope: {agentId: hermes-telegram}
    action: block
  - amountCents: 500
    window: per_day
    scope: {agentId: hermes-cron}
    action: block

Verify the audit log

from agentguard_spend import verify_chain
import pathlib, json

public_key = pathlib.Path("~/.hermes/agentguard/public.key").expanduser().read_bytes()
entries_path = pathlib.Path("~/.hermes/agentguard/decisions.ndjson").expanduser()
entries = [json.loads(line) for line in entries_path.read_text().splitlines()]
result = verify_chain(entries, public_key)
print("OK" if result.ok else f"Chain broken at #{result.sequence}: {result.reason}")

What this plugin does NOT change in Hermes

• Hermes's request retry logic
• Hermes's credential refresh flow
• Hermes's interrupt / cancel pattern
• Hermes's MCP / tool-call layer
• Any of the existing skills

Strictly an LLM-call-intercept layer between Hermes and the Anthropic/OpenAI wire.

Localization

Block traces render in the active locale:

• 🇺🇸 en-US (default)
• 🇲🇽 🇦🇷 🇨🇴 🇨🇱 es-419 (Latin American Spanish)
• 🇧🇷 pt-BR (Brazilian Portuguese)

Resolution chain: explicit AGENTGUARD_LOCALE env var → LC_ALL / LC_MESSAGES / LANG → system locale → en-US fallback.

License

BUSL-1.1. Free for production deployments processing up to 10,000 enforcement calls per calendar month. Commercial licensing for higher volumes or service redistribution: [e-mail].

Patents

Protected by 7 U.S. patent-pending applications (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626; 64/071,781; 64/071,789; plus DV-2026-007 in active filing). See https://agentguard.run/patents.

Links

• Homepage: https://agentguard.run
• Underlying SDK: agentguard-spend (PyPI)
• TypeScript counterpart: @agentguard-run/spend (npm)
• Hermes Agent: https://github.com/NousResearch/hermes-agent
• Contact: [e-mail]