Hermes

Hermes connector stages default-profile hooks and exact approvals for the Hermes agent runtime, with bounded inventory and an explicit reload boundary.

The Hermes connector wires DefenseClaw into the Hermes agent runtime through the effective default-profile HERMES_HOME/config.yaml (%LOCALAPPDATA%\hermes\config.yaml on native Windows when HERMES_HOME is unset) and exact approvals in shell-hooks-allowlist.json.

Platform support

Platform	Status	Connector path
macOS and Linux	Supported	Default-profile configuration and the portable Hermes command hook. Reload every affected Hermes host after lifecycle changes.
Native Windows x64	Supported	Direct, absolute `defenseclaw-hook.exe` argv launched with `shell=False`; no DefenseClaw shell bridge. Running-client state remains pending reload, validation metadata remains empty, and `live=false`.

Hermes terminal commands still use Git Bash on Windows

Hermes itself officially runs its terminal tool through installer-managed PortableGit/Git Bash. DefenseClaw does not install, find, configure, invoke, or test that dependency. Its Windows hook is a separately registered, directly quoted absolute defenseclaw-hook.exe argv launched by Hermes with shell=False; there is no DefenseClaw PowerShell, Bash, WSL, Docker, VM, MSYS, or Cygwin bridge.

Three commands against one Hermes Agent session in observe mode: (1) `echo hello` flows through as action=allow / severity=NONE; (2) `chmod 777 /tmp/dc_test` matches CMD-CHMOD-WORLD HIGH; (3) `cat /etc/shadow` appears as a CRITICAL sensitive-file read in this historical recording. Current builds cap an ordinary sensitive-file read at MEDIUM and keep it detection-only unless the same action proves a mutation or external egress. Observe mode logs without blocking, and supported tool, LLM, session, and subagent events appear in connector activity.

Setup

defenseclaw setup hermes

DefenseClaw stages the default-profile hook configuration and exact allowlist entries. Reload every affected Hermes process after setup.

defenseclaw setup hermes

DefenseClaw registers one directly quoted absolute defenseclaw-hook.exe argv. Hermes parses it with shlex.split and launches it with subprocess.run(..., shell=False), so the command must not contain PowerShell, &, a .ps1, Bash, or WSL. Hermes's own terminal tool separately uses its installer-managed PortableGit/Git Bash; DefenseClaw does not install, locate, invoke, or test that upstream dependency. Reload every affected Hermes host after setup.

setup hermes is shorthand for setup guardrail --connector hermes: it stages hooks in the resolved default-profile config.yaml, adds only the exact 23 DefenseClaw (event, command) approval entries, and inventories the bounded default-profile sources. It preserves the operator's hooks_auto_accept value and third-party approval entries. There is no proxy-enforcement path for Hermes — blocking happens hook-side only when a valid synchronous pre_tool_call stdout response requests block. Hermes has no documented native human-approval or system-message response shape, so confirm verdicts remain audit/alert-only with raw_action preserved for audit.

Discovery keeps installation and contract compatibility distinct. A healthy older client such as v0.17.0 is reported as detected-but-unsupported-version, never as absent. If action mode is requested, Setup prints the exact installed version and the hermes-hooks-v1 >=0.19.0,<0.21.0 requirement, then saves Hermes in observe mode with upgrade guidance. The latest official release rechecked on 2026-08-04 is v0.20.0 (v2026.8.3); its source retains the identical reviewed 23-event shell-hook contract, but that source review is not packaged or real-client certification.

Reload Hermes before treating setup or disable as live

Hermes registers shell callbacks in each running process. DefenseClaw has no vendor-proven command that reloads all Hermes CLI, gateway, desktop, and service hosts, so Setup and Doctor report pending_reload and live: false. Reload or restart every affected Hermes host after Setup and after Disable. Restarting defenseclaw-gateway does not reload Hermes. On Windows, Disable first writes an exact direct-native disabled tombstone so stale cached callbacks safely no-op while revocation is pending.

One default profile only

The connector rejects named-profile homes, a non-default active_profile, and multiplex gateways because one HERMES_HOME cannot cover them. Project plugins and other launch-directory-conditional sources remain unverified. Enterprise, managed, Team, ProgramData, cloud-dashboard, and MDM surfaces are outside this connector contract.

What `setup hermes` actually does

The table highlights convenience options rather than the complete alias surface. The alias also accepts --mode, --rule-pack, --fail-mode, approval, block-message, add/replace, workspace, and rule-pack-directory options. See the quick-alias reference; use full guardrail setup for scanner, detection-strategy, and judge-provider configuration.

Flag	Default	What it does
`--yes / -y`	off	Skip the confirmation prompt.
`--restart / --no-restart`	`--restart`	Bounce `defenseclaw-gateway` after applying changes. This does not reload Hermes; reload each Hermes host separately.
`--with-local-stack / --no-local-stack`	`--no-local-stack`	Also run `setup local-observability up`; follow the command's printed gateway-restart step after it writes the export destination.

The alias defaults Hermes to observe mode and can join an existing hook-connector roster when you choose Add. To tune Hermes after install, keep using defenseclaw setup guardrail --connector hermes — see the variations below.

Common variations — pick the recipe that fits your phase

defenseclaw setup hermes

Confirms once, stages the hooks block and exact allowlist approvals, and restarts the DefenseClaw gateway. Reload each Hermes host before expecting the callbacks to be live. Findings flow to mandatory SQLite event history and the TUI; configured v8 destinations receive only the buckets/signals their routes select. No traffic is intercepted and no requests are blocked. Pass --yes to skip the confirmation in CI.

defenseclaw setup hermes --yes --with-local-stack

Same as standard but also runs setup local-observability up so Prom/Loki/Tempo/Grafana come up locally for ad-hoc dashboards. That command writes the export destination after the alias has already restarted the gateway, so run its printed defenseclaw-gateway restart step before expecting exports. See Local observability.

export DEFENSECLAW_LLM_KEY='replace-with-your-key'

defenseclaw setup hermes                                  # base alias first
defenseclaw setup guardrail \
  --connector hermes \
  --rule-pack strict \
  --scanner-mode local \
  --detection-strategy regex_judge \
  --judge-model anthropic/claude-sonnet-4-20250514 \
  --judge-api-key-env DEFENSECLAW_LLM_KEY \
  --judge-hook-connectors hermes \
  --restart

The alias selects Hermes; the follow-up setup guardrail --connector hermes swaps in the strict rule pack, keeps scanning local, and turns the LLM judge on as a second-pass adjudicator on regex-flagged events. Configure the remote scanner separately through full guardrail setup, which validates its endpoint and API-key environment variable.

Hermes has no proxy enforcement, but its pre-tool hook can enforce directly:

connector_hooks:
  hermes:
    enabled: true
    mode: action          # observe (default) | action
    fail_mode: open       # Hermes is always fail-open at the host boundary

Then defenseclaw setup guardrail --restart to re-wire. With mode: action, Hermes's pre-tool-call hook blocks only when DefenseClaw returns valid synchronous Hermes block JSON. A confirm result is recorded and alerted but returns no hook output because Hermes has no native ask/approve or general message response; the TUI can review the audit event but cannot resume the call. A requested global/per-connector fail_mode: closed, strict availability, timeout, nonzero exit, malformed output, auth failure, or gateway outage cannot create Hermes enforcement and remains fail-open.

Decision aids — should I turn this on?

Human-in-the-loop (HITL)

Per-connector ask matrix. Hermes has no native ask/approve response; confirm is audit/alert-only and returns no hook output.

Full setup guardrail flag reference

All ~20 flags you can pass via `setup guardrail --connector hermes` when tuning Hermes.

Defaults & rule packs

What permissive / default / strict actually ship, and which one matches your risk tolerance.

Interactive wizard

Animated terminal demo of the prompt-by-prompt setup flow — the safest path the first time.

Not sure what to pick? Run defenseclaw setup guardrail (no flags) — the interactive wizard walks you through every choice with safe defaults pre-selected and inline help. The Prompt → flag mapping table gives you the CI-shaped command for the same configuration.

Files DefenseClaw will modify

config.yaml (hooks block)

shell-hooks-allowlist.json (exact owned event/command approvals)

Inventory is read-only and bounded to the resolved default profile: configured MCP, local skills and existing skills.external_dirs, SOUL.md, built-in memories/MEMORY.md and memories/USER.md, memory.provider provenance, and bundled/Nix, user, and pip hermes_agent.plugins plugins with activation provenance. Project plugins depend on launch cwd/environment and are reported unverified; named-profile conditional sources are unsupported.

Hermes stores installer-synced and operator-authored skills in the same tree. DefenseClaw marks a skill vendor-bundled only while its manifest hash, installed copy, and matching hermes-agent/skills source all agree. Those unchanged vendor skills remain visible but are discovery-only: they are never scanned, blocked, disabled, or quarantined. Modified, untracked, linked, or unverifiable copies remain ordinary scanable skills.

Hook capabilities

Block events

pre_tool_call

Native ask events

None — confirm verdicts are downgraded with the raw action preserved.

Hermes can block only pre_tool_call through valid synchronous JSON, inject context at pre_llm_call, and continue its bounded verification loop at pre_verify. DefenseClaw registers all 23 Hermes v0.19 shell-hook-valid events, but transform, API, gateway, approval, Kanban, and ordinary lifecycle events remain attributed audit unless the official shell response parser documents a compatible effect. Hermes does not enforce exit status, timeout, nonzero, malformed, auth, or network failures and has no DefenseClaw ask surface. Confirm verdicts are audit/alert-only, with no synthesized hook output. Registration is not claimed live until Hermes reload evidence exists; Doctor reports the staged state as unhealthy/pending reload.

The official-source record and full cross-surface matrix are in docs/research/HERMES-NATIVE-WINDOWS.md.

Disable

defenseclaw guardrail disable --connector hermes --yes

Then reload or restart every affected Hermes host. Until that happens, the Windows native tombstone keeps any cached exact DefenseClaw callback disabled; DefenseClaw does not manage Hermes's PortableGit terminal behavior.