Hermes
Guard the Hermes agent with DefenseClaw shell hooks that can block a tool call before it runs. Hook contracts, reload boundary, fail behavior, inventory, enterprise handling and the OpenShell sandbox image.
DefenseClaw adds hooks to the default profile's config.yaml and approves exactly those hook commands. DefenseClaw wires 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. This is a hook connector: Hermes talks to its model provider directly and no proxy is involved.
On a per-user install, an explicitly saved guardrail.hook_fail_mode takes precedence over the selected tier. See the gateway outage table and Fail modes.
Platform support
- Min version
- 0.19.0
- Block
- Yes
- Native ask
- No
- Fail closed
- No
- Enterprise
- per-user
| 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 | Hermes starts the protected defenseclaw-hook.exe directly (shell=False), with no DefenseClaw shell bridge. Hermes' own terminal tool uses its bundled Git Bash, which DefenseClaw neither needs nor manages. Reload every affected Hermes host after lifecycle changes. |
Hermes can refuse a foreground terminal command that it classifies as a long-running server or watcher, including an ordinary npm start, before DefenseClaw receives a shell-hook event. This is a Hermes terminal decision; no DefenseClaw verdict or rule ID is available for that refusal.
1.0.7 skill inventory limit
GAP-0486: in a per-user Hermes install using the action profile, vendor skills synchronized by a Hermes store, Nix, or Homebrew install can be treated as user-installed skills and quarantined. Allow a trusted skill by name, or use the observe profile for Hermes. The inventory does not yet have a trusted vendor-hash source for these installs.
At startup, Hermes can ask for approval separately for each shell-hook event registered in its profile. A retained registration pointing at a disabled DefenseClaw hook can therefore produce repeated native approval prompts even though DefenseClaw is not evaluating calls. Check the profile's registered hook commands and the connector's setup/teardown status before approving a stale command; the prompts themselves are issued by Hermes.
Setup
On a new install, run defenseclaw init --connector hermes first. Until DefenseClaw is initialized, defenseclaw setup hermes stops with DefenseClaw is not initialized — run 'defenseclaw init' first.
defenseclaw setup hermes # first setup defaults to observe
defenseclaw setup hermes --mode action # block on policy hitsA re-run without --mode keeps the current mode. On a terminal setup still asks for the mode, with the current one as the default (Enter keeps it), and whether to re-apply the hooks; in action mode it also asks whether to add the LLM judge. --yes skips the questions (the questions setup asks). On Windows, run the same commands in PowerShell. Interactive setup asks for the mode, whether to add to or replace an existing connector roster, and whether to add an LLM judge. For scripts, pass --yes --mode observe (or --mode action).
Reload Hermes before treating setup or disable as live
On macOS and Linux, setup registers the portable hermes-hook.sh in Hermes's config.yaml; macOS and Linux do not write hermes-direct-native-state.json. On Windows, setup registers defenseclaw-hook.exe directly and writes hooks/hermes-direct-native-state.json under the DefenseClaw data directory with "status": "pending_reload". That file records a staged registration, not proof that a running Hermes host loaded it.
Then reload or restart every Hermes host. Hermes registers hooks in each running process, so restarting the DefenseClaw gateway does not reload them. If a Hermes host is running when setup checks the hooks, setup ends that line with ! (restart any open Hermes session so it loads the DefenseClaw hooks). Doctor cannot tell when a host has reloaded; see Check it.
Check it
defenseclaw statusThe agent appears under Agents with its mode.
defenseclaw doctor cannot see which hooks a running Hermes loaded. On macOS and Linux it checks the portable hook registration in config.yaml and whether a Hermes host is running. With a current registration and a running host, the Hermes hooks row warns and names the host PID. For a Linux account with home /home/alice, the row is:
[WARN] Hermes hooks [hermes] — on-disk registration is present at /home/alice/.hermes/config.yaml; Hermes PID(s) 4242; loaded hooks cannot be verified; a new Hermes session loads the current hooks; live=falseOn Windows, doctor checks the native registration in config.yaml, its exact approvals, the hook executable and hooks/hermes-direct-native-state.json. A valid registration is pending-reload; while a Hermes host runs, Hermes hooks and Hook contract warn with live=false and name the PID. macOS and Linux have no direct-native state file to check. Missing or invalid registration still fails doctor.
Close every Hermes host and run defenseclaw doctor again. The warning includes a stop command for the listed PID. With a valid registration and no Hermes running, the row passes on every OS. For that Linux account its detail is registered at /home/alice/.hermes/config.yaml; no Hermes host is running, so the next one starts with the DefenseClaw hooks. On macOS the same check prints the resolved absolute config path; on Windows the pass detail includes the native registration checks. Doctor does not clear the Windows state file. Then start Hermes.
What setup hermes actually does
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 your hooks_auto_accept value and third-party approvals. The connector rejects named-profile homes, a non-default active_profile and multiplex gateways. Project plugins and other launch-directory sources are reported unverified.
On Windows the command is one directly quoted absolute defenseclaw-hook.exe argv. Hermes parses it with shlex.split and launches it with subprocess.run(..., shell=False), so it must contain no PowerShell, &, .ps1, Bash or WSL. DefenseClaw does not install, locate, invoke or test Hermes's PortableGit.
| Flag | Default | What it does |
|---|---|---|
--yes / -y | off | Skip the confirmation prompt. |
--restart / --no-restart | --restart | Bounce defenseclaw-gateway. This does not reload Hermes. |
--with-local-stack / --no-local-stack | --no-local-stack | Also run setup local-observability up. Run its printed gateway-restart step before expecting exports. |
The alias also accepts --mode, --rule-pack, --fail-mode, approval, block-message, add/replace and workspace options (quick-alias reference). To tune Hermes later, use defenseclaw setup guardrail --connector hermes. On a host with several connectors, defenseclaw setup guardrail --connector hermes --mode action switches only Hermes.
Hermes registers shell callbacks in each running process, and DefenseClaw has no vendor-proven command that reloads every Hermes CLI, gateway, desktop and service host. On macOS and Linux, setup registers the portable hermes-hook.sh and writes no direct-native reload state file. On native Windows, setup writes hooks/hermes-direct-native-state.json under the data directory; disable first writes a direct-native disabled tombstone to that file so stale cached callbacks no-op while revocation is pending. This file does not prove what a running host loaded. While a Hermes host runs on any OS, setup ends its check line with ! (restart any open Hermes session so it loads the DefenseClaw hooks) and doctor warns on the Hermes hooks row with live=false when the registration is current (Check it). Reload every host after setup and after disable. Restarting defenseclaw-gateway does not reload Hermes.
verify and doctor check the exact command in Hermes's active registration and run a bounded local execution probe. A missing executable bit, a broken hook helper, or a disabled Windows launcher fails the check. The probe sends no tool event to the gateway; a real Hermes call after restarting its host is still the live confirmation that the callback is loaded.
On Linux the probe runs in a PID namespace of its own, inside a user namespace unless the checking process has CAP_SYS_ADMIN, so nothing the hook starts outlives the probe. Where the host cannot create that user namespace (user namespaces disabled with user.max_user_namespaces=0, or a container seccomp profile that refuses them), the probe cannot run. A registration whose hook script still has the digest setup sealed stays current. Setup reports ready, and doctor warns execution proof unavailable: the sealed registration was read back without running it. An edited hook script is not current. A probe that ran and failed is a plain failure. A fail-mode change (--fail-mode) and the fail-mode status do not run the probe: they check the registration, its approvals and the sealed hook.
Per-user setup accepts a Hermes git install that prints only its release date, for example Hermes Agent vunknown (2026.9.24), when that date is a supported release.
Files DefenseClaw will modify
| What | Where |
|---|---|
| Hooks | $HERMES_HOME/config.yaml, hooks block (Windows default %LOCALAPPDATA%\hermes\config.yaml) |
| Approvals | shell-hooks-allowlist.json in the same folder |
| Hook program, macOS and Linux | ~/.defenseclaw/hooks/hermes-hook.sh |
| Reload state, Windows only | hooks/hermes-direct-native-state.json under the DefenseClaw data directory |
| Hook program, Windows | %USERPROFILE%\.local\bin\defenseclaw-hook.exe (one-line install) or %LOCALAPPDATA%\DefenseClaw\HookRuntime\defenseclaw-hook.exe (Setup installer) |
| Hook program, managed Windows | C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw-hook.exe, written by the guardian into each enrolled account's %LOCALAPPDATA%\hermes\config.yaml |
Disable removes only DefenseClaw's entries and approvals. Settings and comments outside the hooks mapping are kept; whitespace can change. On Linux and macOS hermes-hook.sh stays as an inert stub, because a running Hermes keeps calling it until it restarts.
Inventory
Read-only and bounded to the resolved default profile: configured MCP, local skills and skills.external_dirs, SOUL.md, memories/MEMORY.md and memories/USER.md, memory.provider provenance, and bundled, Nix, user and pip hermes_agent.plugins with activation provenance. Hermes keeps installer-synced and operator-authored skills in one tree. A skill is vendor-bundled only while its complete tree matches a vendor digest shipped with DefenseClaw. Those are listed but never scanned, blocked, disabled or quarantined. Modified, unlisted, linked or unverifiable copies are ordinary scannable skills.
Hook capabilities
Block events
- pre_tool_call
Native ask events
None — confirm verdicts are downgraded with the raw action preserved.
| Contract | Agent versions | Hook script | Events | Can block | Can ask |
|---|---|---|---|---|---|
hermes-hooks-v1 | >=0.19.0, <0.21.0; exact pins 2026.7.20, 2026.7.30, 2026.8.3, 2026.8.13, 2026.8.16, 2026.8.16.2, 2026.8.18, 2026.8.19, 2026.8.27 | v6 | 23 | 1 | 0 |
hermes-hooks-v2 | >=0.21.0, <0.22.0; exact pins 2026.8.31, 2026.9.7, 2026.9.11, 2026.9.14, 2026.9.21, 2026.9.24 | v6 | 23 | 1 | 0 |
| Contract | Events registered | Block events | Ask events |
|---|---|---|---|
hermes-hooks-v1 | pre_tool_call, post_tool_call, transform_terminal_output, transform_tool_result, transform_llm_output, pre_llm_call, post_llm_call, pre_verify, pre_api_request, post_api_request, api_request_error, on_session_start, on_session_end, on_session_finalize, on_session_reset, subagent_start, subagent_stop, pre_gateway_dispatch, pre_approval_request, post_approval_response, kanban_task_claimed, kanban_task_completed, kanban_task_blocked | pre_tool_call | none |
hermes-hooks-v2 | As the previous contract | pre_tool_call | none |
| Fact | Value |
|---|---|
| Hook script | hermes-hook.sh |
| Hook config paths | $HERMES_HOME/config.yaml, %LOCALAPPDATA%/hermes/config.yaml, ~/.hermes/config.yaml |
| Response field | hook_output |
| Native OTLP | no |
| W3C traceparent | yes |
| Fail closed | No across all process failures. Hermes 0.21 closes timeout and spawn error after Setup and restart; a killed hook can still fail open. Hermes 0.19/0.20 also fail open on timeout. |
On the host, Hermes 0.19.0 to 0.21.0 (release dates 2026.7.20 up to 2026.9.7, and a git build that prints one of those dates) have a known gap. Their TUI (hermes --tui) and dashboard chat start their agent without registering the config.yaml shell hooks, so a terminal call there runs with no pre_tool_call and is neither blocked nor recorded. Their classic interface (hermes, hermes chat), cron, ACP and messaging gateway run the hooks. DefenseClaw does not own the hermes command on the host and cannot refuse the TUI there, so setup registers the hooks in observe and action mode and warns, defenseclaw doctor shows a warning on the Hermes compatibility row, and the gateway logs the warning at every start. Hermes 0.21.1 is the first release that registers the hooks there too (upstream fix). Use the classic interface, or update Hermes (hermes update) to 0.21.1 or later. The newest Hermes on PyPI is 0.19.0, so a PyPI install has to move to the official installer to update.
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. Setup prints the installed version and the hermes-hooks-v1 >=0.19.0,<0.21.0 or hermes-hooks-v2 >=0.21.0,<0.22.0 requirement and refuses Hermes in observe and action mode, without changing anything (Hook contracts). The latest official release rechecked on 2026-09-14 is v0.21.3 (v2026.9.14). Its source keeps the same 23 claimed shell-hook events, but that source review is not packaged or real-client certification (live: false in validated_versions.json).
What it can block or ask
What a gateway outage does to a Hermes call, per install and fail mode, is in the gateway outage table.
- Only
pre_tool_callcan block, and only when the hook returns valid block JSON. - Hermes has no hook that stops a prompt. A matching prompt reaches the model. Tool-call rules still block.
- Hermes has no native ask. A confirm verdict is recorded and alerted, and the hook returns nothing. The standalone enterprise profile blocks it instead.
- The other registered events are audit only.
Verdict mapping
| Topic | Behavior |
|---|---|
| Blocking | Only pre_tool_call blocks, through a valid synchronous block answer, and from Hermes 0.21 on exit code 2. pre_llm_call can inject context and pre_verify can continue its bounded verification loop. |
| Registered events | All 23 Hermes v0.19 shell-hook-valid events. Transform, API, gateway, approval, Kanban and ordinary lifecycle events stay attributed audit unless Hermes documents a compatible effect. |
| Other exits | Hermes 0.19/0.20 can run the call on a killed or timed-out hook. For the reviewed 0.21 contract, DefenseClaw sets fail_closed: true only on pre_tool_call, so a spawn error, timeout or unparseable nonempty stdout blocks. A killed hook can still fail open with a non-2 exit and empty stdout. Other events remain non-blocking. |
| Confirm | Hermes has no native ask or message response. A confirm is recorded and alerted, the hook returns nothing, and the TUI can review but not resume. The standalone enterprise profile blocks a confirmed pre_tool_call instead, with a message that the organization's rule needs a confirmation Hermes cannot ask for. |
| Hook fail mode | On Linux, macOS and Windows an auth failure or unusable answer blocks the call with Hermes' block answer and names the next step, such as defenseclaw-gateway start. A gateway that is not running follows the policy tier on a per-user install and the administrator's fail mode on a managed host (gateway outage table). In 0.21 the vendor fail_closed setting also blocks when the hook process fails or times out, even though that failure never reaches the gateway; Hermes 0.19/0.20 still run the call when the hook times out or cannot start. A call that runs unchecked during an outage is recorded in ~/.defenseclaw/logs/hook-failures.jsonl; on a per-user install it is reported as a guardrail-degraded alert when the gateway starts again. A managed gateway raises no such alert: on a managed host whose administrator selected open, the call keeps only that account's hook-failures.jsonl line (outcome fail_open). |
| Managed standalone | The hook blocks a pre_tool_call whose answer it cannot use or that is too large to inspect, in every fail mode. A gateway that is not running blocks the call under the administrator's closed fail mode (the default). On Linux and macOS it also blocks the call through the foreign-hook guard while foreign_hooks is remove (the default), unless the fail mode is open and the agent process has a current clean-session note. On Windows, where Hermes has no guard, an administrator's open lets the call run during an outage: the user's hook-failures.jsonl gets a line with fail_mode open and outcome fail_open. Hermes shows no hook text itself; the text goes to the model as the tool's error. A fail-mode block is a fail_mode: closed line in the user's hook-failures.jsonl. |
Hermes 0.21/0.22 sends a blocked pre_tool_call message to the model as a tool error. DefenseClaw starts that message with DefenseClaw blocked this call: <rule>: <reason>. The Hermes TUI does not display the hook message directly and may show only the model's summary. This is the same display limit described in GAP-0138. During an outage, the hook writes a warning to stderr when policy allows the call; Hermes does not provide a TUI notice for that warning.
Native ask
Hermes has no native ask surface. A confirm verdict is recorded and alerted, the hook returns nothing, and the TUI can review but not resume. The standalone enterprise profile blocks a confirmed pre_tool_call instead.
Fail mode
Fail closed on timeout and spawn error for a reviewed Hermes 0.21 pre_tool_call registration after Setup or guardian reconciliation and agent restart; Setup sets the vendor fail_closed field. A killed hook can still fail open because Hermes treats a non-2 exit with empty stdout as no decision. Hermes 0.19/0.20 cannot block a timed-out or killed hook process. A running DefenseClaw hook blocks pre_tool_call on an auth failure or an unusable answer on all three OSes. A gateway that is not running follows the policy tier on a per-user install: the default and permissive policies let the call run with one warning, and the strict policy blocks it (gateway outage table). Settings and edge cases are in Fail modes.
OpenShell sandbox
DefenseClaw builds a Hermes overlay image. Nothing on your host changes. defenseclaw sandbox run hermes runs it (guide).
| Item | Detail |
|---|---|
| Tier | User, on a managed layer. Hermes 0.19 reads /etc/hermes/config.yaml and merges it over ~/.hermes/config.yaml key by key, managed value winning. The image registers the hook for all 23 events there and pins hooks_auto_accept: true, plugins.enabled: [], terminal.backend: local, agent.disabled_toolsets: [code_execution], security.tirith_enabled: false, security.allow_lazy_installs: false, model_catalog.enabled: false and display.interface: cli. A user setting can add hooks for other events but cannot drop or replace DefenseClaw's. Hermes still reads ~/.hermes/.env (where HERMES_SAFE_MODE switches hooks off and HERMES_MANAGED_DIR moves the managed layer) and imports model-provider plugins from ~/.hermes/plugins/model-providers, so the hooks depend on the launcher's checks and the tier is user. |
| Launcher checks | The root-owned launcher refuses to start while an argument is --safe-mode or an accepted prefix (--sa and longer; DefenseClaw's own --safe goes before the harness name), a .env or .op.env in the Hermes home or a profile names a variable that switches hooks off, moves the managed layer or home, or loads other code (HERMES_SAFE_MODE, HERMES_MANAGED_DIR, HERMES_HOME, HERMES_ENABLE_PROJECT_PLUGINS, HERMES_PYTHON*, PYTHON*, LD_* and more), the home or a profile holds Python under plugins/, or a user config.yaml has a secrets section. It pins HOME, HERMES_HOME and HERMES_MANAGED_DIR=/etc/hermes, so Hermes always reads the managed layer, and drops PYTHON* variables. /etc/hermes/.env pins safe mode and project plugins off and HERMES_TUI=0. The refusal names the file. |
| Fail closed | Hermes 0.19 ignores a hook's exit status and treats a timeout as no opinion, so the sandbox hook prints a Hermes block directive on every failure, well inside the 30-second timeout. |
| Blocks on screen | Hermes 0.19 shows nothing for a blocked call except preparing terminal…. A root-owned module prints the reason under it (for example ┊ ✗ terminal blocked: DefenseClaw policy blocked this action (rule <ID>: <title>). …), only to a terminal. The model gets the same reason. |
| Known gaps | The pinned Hermes 0.19.0 runs tools in its TUI (hermes --tui), dashboard chat and hermes serve without the hooks, so the sandbox keeps Hermes on its classic interface, which runs the hooks: a start that Hermes runs as its TUI is refused where Hermes starts the TUI, while every start it runs as the classic interface goes ahead (hermes --cli --tui, hermes --tui --version), the managed layer pins display.interface: cli and HERMES_TUI=0 over your settings, and the agent those modes build refuses to start. An agent can start a second Hermes from a tool call, skipping the launcher checks. DefenseClaw judges that call first and hook-silence detection is the backstop. Command rules judge the terminal tool and the text the process tool sends to a background process. The image turns off execute_code. A script the agent writes and runs is judged by the command that starts it. |
| Install pin | Hermes Agent 0.19.0 from PyPI as a root-owned uv tool on private CPython 3.12.13, with dependency resolution cut off at the review date. The build refuses a version outside >=0.19.0,<0.22.0. |
| Model access | defenseclaw-openai or the regional defenseclaw-bedrock-mantle-openai-<region> through the managed defenseclaw provider (--provider defenseclaw -m <model>), or defenseclaw-anthropic through the built-in anthropic provider. Keys are OpenShell placeholders valid only at the endpoint and for the harness's interpreter. sandbox run hermes picks the first set of OPENAI_API_KEY, ANTHROPIC_API_KEY and AWS_BEARER_TOKEN_BEDROCK (--llm picks one). |
| Model limit | On the reviewed Bedrock-Mantle defenseclaw-openai route, sandboxed Hermes 0.19.0 cannot complete a call to openai.gpt-5.6-luna: the provider returns HTTP 400 validation_error (model not supported on this route), even though authenticated GET /v1/models lists it. Direct controls with max_tokens and max_completion_tokens returned the same route error, so this result does not identify a parameter-shape cause. Hermes 0.21 on a host configured for the Responses/Bedrock route succeeded. This is a provider-route limit, not a DefenseClaw block; use a supported sandbox model or the separately configured host route. |
| Launch flags | Skip-permissions adds --yolo. --safe drops it and every prefix Hermes accepts. A headless run is hermes chat -q <prompt> -Q; pass -- chat -q "TEXT" to sandbox run. |
| Ctrl-Z and Ctrl-C | The sandbox refuses Hermes's process-group signal, so the image answers with defenseclaw: Ctrl-Z cannot suspend a harness in an OpenShell sandbox … and Hermes keeps running (Hermes prints its own "has been suspended" line first). One Ctrl-C at an empty prompt ends Hermes (Shutting down… (finalizing session)) and DefenseClaw goes on to the end of the session. The sandbox is kept, and defenseclaw sandbox connect <name> restarts Hermes. |
| Other traffic | Apart from the model, Hermes reaches models.dev at start and hourly (model metadata, no off switch). sandbox destinations lists it as Hermes' own, and a pack that refuses it does so quietly. The image marks the install docker so Hermes does not check pypi.org or print the pip notice. model_catalog.enabled: false stops the curated model-list fetch, and the Tirith download and runtime installs are off. The rest goes through the egress proxy. |
| Status | Verified end to end through the daemon on a mock model: hooks reached the ingress with OpenShell substituting the key, a rule-blocked command was refused with the rule's reason, and egress went through the proxy, including a blocklisted host that a sandbox-scoped unblock let through. The hook-fire probe passed, including a hostile user config.yaml, a planted sitecustomize, and a launcher refusal for a planted .env, provider plugin or secrets section. The curated provider profiles have not carried a real model inside a sandbox. |
Enterprise deployments
Enterprise standalone profile
The guardian writes the hooks into each enrolled user's default config.yaml and repairs them. The profile writes no machine-wide Hermes configuration, so coverage is advisory against a user who sets out to avoid it.
hermes --safe-modeskips the user'sconfig.yaml, and aHERMES_HOMEpointing at a copy without thehooksblock does the same. No hook runs and the guardian cannot repair that session. Managed ensure, status and verify mark session-home coverage unproven; status and verify also report a running bypass as incomplete and audit the observation.--ignore-user-configalone keeps the hooks.hermes-hook.shruns as the user. Hermes 0.19/0.20 can run a call after the user kills or stalls the hook, with no pre-tool decision; a laterpost_tool_callmay still record it. In the reviewed 0.21 contract, Setup now writesfail_closed: trueonpre_tool_call, so a timed-out hook or spawn error blocks once the agent loads the new registration. A killed hook can still fail open with a non-2 exit and empty stdout. A Hermes session already running at upgrade must restart.- Hermes runs every hook registered for an event, in order, and a
pre_tool_callhook can rewrite tool input. Hermes cannot lock or order hooks. On Linux and macOS the hook runs the foreign-hook guard before each call. Whileconfig.yaml, or the managed-scope file in the folderHERMES_MANAGED_DIRnames, has an unapproved foreign hook entry, tool calls are blocked with a message naming the file and the digest to approve, and the guardian removes the entry (with a backup). A Hermes process that started with the entry keeps running it, so it stays blocked until restart. Theoutput_spillandoutboundsettings underhooksare not hooks.
To reduce this, prefer agents governed through machine policy, use application control so users start Hermes only from an administrator-owned launcher that resets HERMES_HOME and HERMES_MANAGED_DIR and refuses --safe-mode and --ignore-user-config, and use EDR process protection so users cannot kill the hook. See R1, R5 and R18 in the threat model.
On a managed computer
The per-user commands on this page do not run on a computer with a standalone enterprise install. On Linux and macOS, defenseclaw there runs only the commands in Managed command availability: anything else prints "This computer is managed; use defenseclaw status for your protection state, defenseclaw sandbox status for your sandboxes and defenseclaw sandbox policy explain for your policy." followed, on Linux and macOS, by the administrator views of that computer (the installed gateway's enterprise linux status or enterprise macos status, verify and audit export --since 2h) and exits 2. On native Windows, the administrator's command is defenseclaw.exe, run by its full path because Setup puts nothing on PATH: it refuses setup hermes and setup remove, and refuses guardrail commands (exit 3). Hermes is protected per user: the guardian writes the hooks and exact approvals into each enrolled account's Hermes config.
The administrator manages Hermes in the managed config.yaml. guardrail.connectors.hermes: {} adds it for the accounts that enrollment selects, the connector's mode and hook_fail_mode tune it, and guardrail.connectors.hermes.enabled: false removes it. Apply the change as in Change the config, then check it with enterprise <os> verify --json (on Windows add --profile standalone; see Operations). On Windows, machine ensure and upgrade can complete while an enrolled Hermes account reports NOT COVERED: a session-only HERMES_HOME may select a home the guardian cannot see or hook. Ensure, status, verify and the managed doctor answer name this limit; the lifecycle records a managed coverage alert. Managed verification reports session-home coverage as unknown because a shell can select an unhooked HERMES_HOME after the guardian checks. On Linux and macOS, enterprise hooks verify --json as root also checks the current hook files and reports this limit. enterprise policy verify checks machine-policy connectors only. See Managed verification.
Managed verification
enterprise <os> status --json and verify --json report connectors.hermes.hooks_installed and targets. On Linux and macOS the target rows come from the guardian's last reconcile and do not prove what a running Hermes host has loaded. Managed Hermes hook coverage is reported as unknown when Hermes is present or discovery is unknown.
On a managed host, enterprise hooks verify always exits 1 for Hermes rows: each row says connector hermes cannot be verified: session-only HERMES_HOME cannot be observed by the managed service. That is the session-only limit, not tampering. enterprise linux verify and enterprise macos verify report the same limit as a NOT COVERED warning and exit 0.
To check the current hook files on Linux, run sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise hooks verify --json. On macOS use sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise hooks verify --json. Missing or changed owned commands fail this check. Managed Hermes also reports that it cannot certify a session-only HERMES_HOME; file integrity alone does not prove launch coverage. Reload every Hermes host after repair.
enterprise policy verify checks machine-policy connectors; Hermes uses per-user hooks, so that command can succeed while its hooks are missing.
The guardian sets up and checks the Hermes home each account configured, not the profile default. On Windows that is the HERMES_HOME of the account's persistent environment (its own variable, else the machine's), else hermes under the Local AppData of its sign-in, read from the account's loaded registry hive. While the account is signed out the hive is not loaded, so its hooks are not set up or checked until it signs in; the check never falls back to the default folder. On Linux and macOS the guardian uses ~/.hermes, and its persistent-home check fails when it finds another home. That check reports HERMES_HOME unproven when any of these sets HERMES_HOME to another home, or to a value a service cannot resolve:
- a
HERMES_HOMEthat DefenseClaw hooks recorded in the account's~/.defenseclaw/foreign-hook-env.json, on every platform; ~/.config/environment.d/*.conf,/etc/environment.d/*.conf,/etc/environment,~/.pam_environmentor/etc/security/pam_env.conf, where$HOME,${HOME},@{HOME}and a leading~are resolved;- any uncommented line naming
HERMES_HOMEin a shell startup file (~/.profile,~/.bashrc,~/.zshrc,~/.zshenv, the fish config,/etc/profile,/etc/profile.d/*and the system bash and zsh files), because only the shell can evaluate it; - on macOS, the account's launchd environment (
launchctl setenv HERMES_HOME); - the environment of any running process of the account, which shows a
HERMES_HOMEset by a file a startup file sources, a terminal profile or an IDE. Linux reads/proc; macOS readskern.procargs2, and withholds the environment of Apple's own programs, such as/bin/zsh, even from root.
On standalone managed Linux, macOS and Windows, setup still installs hooks in the persistent home, but verify cannot certify every Hermes launch. A user can set HERMES_HOME only in an already-running shell, selecting an unhooked home without writing a persistent setting or running an existing hook. The service cannot discover every such home. On Windows, machine ensure and upgrade complete when the installed registrations pass their checks; the account's enrollment reason says Hermes NOT COVERED for the session-only home. Ensure, status and verify name the same limit, and ensure records a managed coverage alert. Status reports hooks_installed: unknown, with security and coverage incomplete, when Hermes is present or discovery is unknown; verify refuses certification and names the session-only limit. The managed Windows doctor answer points users to the administrator's status and verify. Secure Client keeps its separate behavior.
Some settings are not caught by the persistent-home check: a HERMES_HOME exported from a file that a startup file sources (an oh-my-zsh custom file, ~/.zsh/env.zsh), or from a terminal or IDE profile, shows only in the processes started with it. On macOS, Apple's shells hide even that. While Hermes and every other non-Apple program started with that setting are stopped, the check finds nothing at the alternate home. To establish launch coverage, let users start Hermes only from an administrator-owned launcher that pins HERMES_HOME.
To clear a persistent-home mismatch, remove the setting that names the other home. A HERMES_HOME the hooks recorded keeps failing the check until a Setup of Hermes supersedes it. That happens when Hermes is set up for the account again (enterprise hooks install, or the guardian's repair) a day or more after the last agent ran with that HERMES_HOME. The hooks refresh a recorded entry they see again after a day. So an entry that old when Setup ran has not been used since, and the check skips it. An entry seen since that Setup, or less than a day before it, still fails the check. On every platform a named profile Hermes would run from (active_profile naming another profile, or a folder under profiles/) fails the check, because the hooks are in the default profile. Clearing that mismatch does not establish universal session coverage.
When the configured home changes, for example after an upgrade from 1.0.3 on Windows, where the guardian set up %LOCALAPPDATA%\hermes even when the account set HERMES_HOME, setup first removes DefenseClaw's hooks and approvals from the earlier home and then sets up the configured one. Teardown and connector prune-orphans also clean DefenseClaw's entries out of the profile default home, and teardown verification fails while any remain.
Limits
- The connector covers the default profile only. Named-profile homes and multiplex gateways are rejected.
- Only
pre_tool_callblocks. The other events are attributed audit unless Hermes documents a compatible effect. - Hermes shows no block line for a call a hook blocks. DefenseClaw sends the rule and reason to the model as the tool error (
DefenseClaw blocked this call: <rule>: <reason>), and the model relays it in its own words, so the Hermes screen, also with/verbose, may show only that paraphrase. The block itself holds. The rule and reason are always recorded: read them withdefenseclaw alertsor in the Alerts panel of the DefenseClaw TUI. - Hermes 0.19/0.20 can run a call when a hook times out or cannot start. In the reviewed 0.21 contract, Setup or guardian reconciliation writes
fail_closed: trueforpre_tool_call, so a timeout or spawn error blocks after the Hermes host loads that registration. Restart every running Hermes host after the change. A killed hook can still let a call run on a non-2 exit with empty stdout. A valid block answer blocks in all supported versions; 0.21 also blocks on exit code 2. - Hermes runs every hook registered for an event, in order. A hook added after DefenseClaw's can change a command DefenseClaw already checked. Hermes cannot lock or order hooks, so a foreign
pre_tool_callhook can rewrite tool input. hermes --safe-mode, or aHERMES_HOMEwithout thehooksblock, runs with no DefenseClaw hook. Managed ensure, status and verify mark session-home coverage unknown; status and verify also report a running bypass as incomplete.- Hermes registers shell callbacks per process. A host that is not reloaded keeps its old state, also after you turn the connector off.
- Hermes MCP startup can fail before any hook when
pm-runtimecannot read the sharedinstall-stamp.jsonor the tools installer cannot create$HERMES_HOME/tools/.install.lock. Inspect the resolved path, owner, and permissions for the affected account. No DefenseClaw verdict was recorded for these failures (Agent messages that are not from DefenseClaw).
Disable
On a managed computer, the administrator sets guardrail.connectors.hermes.enabled: false in the managed config.yaml and runs ensure (On a managed computer); the commands below are refused there.
For a per-user, single-connector install:
defenseclaw guardrail disable --yesWith the default gateway restart, disabling removes DefenseClaw's hooks and their approvals from Hermes's config and allowlist. It preserves your other Hermes settings. defenseclaw guardrail enable restores DefenseClaw's hooks and approvals. To remove the connector, run defenseclaw setup remove hermes --yes (add --force if it is the last one). Then reload every Hermes host.
On a multi-connector install, add --connector hermes to guardrail disable and guardrail enable to change only this agent.
Cursor
Cursor connector installs user hooks that observe events or deny actions before they run. Action mode denies with Cursor's own response and does not enable native ask.
OpenCode
Guard OpenCode V2 with a dependency-free plugin that rejects risky tool calls before they run. Version contract, setup, upgrade from V1, files, limits and managed deployment.