hermes-acp

ACP governance plugin for Hermes Agent.

Routes every tool call through the Agentic Control Plane so you get:

• Audit — every tool call (terminal, file, web, browser, custom skills) is logged with tenant + session attribution.
• Veto — server-side policy can deny or require approval on individual tool calls before they execute.

Companion to the Claude Code ACP plugin. Same backend contract, same dashboard, same policies — just wired into Hermes's Python plugin system instead of Claude Code's shell hooks.

Install

pip install hermes-acp
hermes plugins enable acp
hermes-acp login

hermes-acp login opens the dashboard, exchanges your one-time auth token for a workspace API key, and writes it to ~/.acp/credentials.

Configure

For non-interactive setups (CI, devcontainers), skip the login step and provide the key directly:

export ACP_BEARER_TOKEN="gsk_yourslug_..."
# or
mkdir -p ~/.acp && echo "gsk_yourslug_..." > ~/.acp/credentials

The env var wins over the file.

CLI

hermes-acp login       # browser-based authentication + workspace provisioning
hermes-acp status      # check creds + gateway reachability
hermes-acp logout      # remove ~/.acp/credentials

Optional — point at a non-default backend:

export ACP_API_BASE="https://api.agenticcontrolplane.com"  # default

How it works

The plugin registers two Hermes hooks:

Fail-open

Network errors, timeouts (>4s), or malformed responses fail open — the tool call proceeds and a warning is written to stderr. ACP outages should never block your work. Server-side per-tenant failMode: closed can flip this in a future release.

"Ask" semantic

Hermes doesn't support inline approval prompts the way Claude Code does, so an ACP ask decision is rendered as a block with a message instructing the user to approve in the ACP dashboard and retry. If you want a richer approval UX in Hermes, this is the spot to extend.

Client identity

Sends X-GS-Client: hermes-plugin/<version> so the dashboard, policy router, and audit log can distinguish Hermes traffic from Claude Code / Cursor / Codex / etc.

Troubleshooting

No audit events appearing. Check that ACP_BEARER_TOKEN is set in the shell that launched hermes, not just your .zshrc after the fact. Hermes inherits the env at process start.

Every tool call blocked. Look at stderr. A [ACP] gateway unreachable warning means network failure (fail-open kicked in but something else blocked you — maybe a policy from another hook). A [ACP] Denied by policy: … means the server returned deny; check the policy in the ACP dashboard.

Hooks not firing at all. Confirm the plugin is enabled: hermes plugins list. If acp isn't in the enabled list, run hermes plugins enable acp.

License

MIT