mordred-hermes

Privacy-preserving plugin bundle for the Hermes agent: at-rest encryption for your secrets (.env, config, agent memory), hardware-backed key management (Secure Enclave / TPM 2.0), Tor / VPN network routing, and policy enforcement for local-only LLM operation.

Status: active alpha — current release 0.1.0a10 (PyPI has the release history and dates).

New here? The step-by-step QUICKSTART takes you from zero to a protected install.

⭐ Recommended: set up with an AI coding agent. The first-run setup (configure, network init, keyvault init) is a series of interactive ceremonies with several prompts. Running them inside Claude Code or Codex is the recommended path — the agent walks you through each prompt, explains the options, and picks sensible defaults for your platform.

The plugins

The Mordred entry-point plugins, exposed via the hermes_agent.plugins entry-point group:

Requirements

• Python ≥ 3.11 (CI tests 3.11–3.13)
• hermes-agent ≥ 0.13.0 (its first PyPI release — older versions were never published and are not installable). The floor is exercised in CI on every PR (the hermes-floor job pins it exactly); behavior against the latest release was last verified on 0.19.0, 2026-07-21
• macOS or Linux. macOS can fall back to a software P-256 key in the login Keychain when Secure Enclave access is unavailable. Linux keyvault setup requires the TPM 2.0 helper and fails closed when it is absent.

Install (users, from PyPI)

Install into the same environment that runs hermes-agent (usually ~/.hermes/hermes-agent/venv) so its plugin loader can discover the entry points. Hermes-managed venvs are often created by uv and ship no pip, so the robust form is uv pip install --python … (no uv on your machine? Install it first — brew install uv on macOS, or see the uv installation guide):

# macOS — includes the Secure Enclave keyvault stack
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 "mordred-hermes[macos]==0.1.0a10"

# Linux — cross-platform crypto stack for `encryption` / `keyvault`
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 "mordred-hermes[keyvault]==0.1.0a10"

(If your venv does have pip, ~/.hermes/hermes-agent/venv/bin/pip install … works the same.) The pinned form above is the recommended default — it's deterministic and reproducible. Prefer not to look up the current version? The unpinned --upgrade form resolves to the newest pre-release — every release is currently a pre-release, so the all-prereleases fallback applies (the same goes for plain pip, which also accepts an explicit --pre; see Upgrading for the same command used to update later):

# macOS — newest release without a version lookup; use [keyvault] on Linux
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 --upgrade "mordred-hermes[macos]"

Optional extras, all opt-in:

Enable the plugins

Running hermes-mordred configure (next section) does this for you — every run back-fills all six mordred_* entries into plugins.enabled in ~/.hermes/config.yaml if they're missing, so there's no manual step. Afterwards ~/.hermes/config.yaml should contain:

plugins:
  enabled:
    - mordred_privacy_check
    - mordred_wizard
    - mordred_llm_guard
    - mordred_network
    - mordred_keyvault
    - mordred_e2e

Only edit this by hand if you want the plugins enabled before the first configure run — otherwise there's nothing to do here.

Use it

The CLI is the standalone hermes-mordred console script (installed next to hermes in the same venv):

M=~/.hermes/hermes-agent/venv/bin/hermes-mordred

# First run — set up, in order:
$M configure                       # interactive Mordred setup (policy / LLM / harness)
$M network init                    # optional — pick a privacy route (Tor / VPN / clearnet)
$M keyvault enable-se              # macOS — install/refresh and probe the SE helper
MORDRED_SEKEY_UNATTENDED=1 $M keyvault init
                                    # create a no-Touch-ID hardware key (interactive ceremony)
$M encryption enable env           # encrypt your .env at rest
$M status                          # verify — the `env` row reads [on] enrolled

# Everyday commands:
$M status                          # protection at a glance
$M encryption status               # what's encrypted (env / config / memory)
$M encryption enable <target>      # turn on at-rest encryption for a target
$M network use <tor|vpn|clearnet>  # switch the active privacy route
$M network status                  # show the active route and liveness
$M encryption change-passphrase    # rotate the vault recovery passphrase
$M configure                       # re-run interactive setup anytime
$M configure --with-hermes-setup   # re-run and include the upstream `hermes setup` wizard

Why unattended key creation is recommended on macOS. The default attended device key asks for Touch ID on every vault unwrap — a background process (a launchd-started gateway, extension serve) can never answer that prompt and silently starts without the vault-managed secrets. enable-se only installs/probes the helper; it does not create, promote, or migrate a wrapping key. It is safe to refresh with an existing vault: existing helper, legacy Keychain, and software keys remain in their current namespace and continue through backend fallback. Set MORDRED_SEKEY_UNATTENDED=1 on a later fresh keyvault init (or recovery) command: the attended/unattended choice is fixed at key creation. Already hit this, or want the full trade-off? See Troubleshooting below.

Network troubleshooting. If network communication drops out now and then, check the active privacy path first — network status tells you whether Tor / VPN is actually up:

$M network status
# active_path = tor  state = ready      last_health = ok       ← path is up
# active_path = tor  state = not ready  last_health = FAILED   ← path is down

state is ready / not ready, last_health is ok / FAILED. A trailing [warning] path was flagged as DROPPED line means the liveness worker saw consecutive failures; in strict mode tool calls refuse until you re-establish the path with network use <tor|vpn|clearnet>.

Step-by-step guide with expected output: QUICKSTART. Full command reference and interactive-command walkthroughs: USAGE.

Why not hermes mordred …? Hermes does not yet wire entry-point CLI commands into its argparse (still true on 0.18.2) — hermes-mordred is the same subcommand tree and works today. Once upstream wires it, both forms will coexist without code changes.

Verify discovery

Use Mordred's own command — it lists the Mordred plugins on any supported Hermes version:

~/.hermes/hermes-agent/venv/bin/hermes-mordred plugins list
# → mordred_e2e / mordred_keyvault / mordred_llm_guard / mordred_network / mordred_privacy_check / mordred_wizard

The host hermes plugins list scans plugin directories only (bundled / user / project), so it does not list entry-point plugins like these. To confirm the loader itself discovers them, query it directly:

~/.hermes/hermes-agent/venv/bin/python3 -c "
from hermes_cli.plugins import PluginManager
mgr = PluginManager(); mgr.discover_and_load(force=True)
print(sorted(k for k, p in mgr._plugins.items() if p.manifest.source == 'entrypoint'))
"
# → ['mordred_e2e', 'mordred_keyvault', 'mordred_llm_guard', 'mordred_network', 'mordred_privacy_check', 'mordred_wizard']

Browser-extension WebSocket gateway (preview)

mordred_hermes.extension ships the WebSocket server the Mordred browser extension talks to — ws://127.0.0.1:7788/ext, localhost-only, no TLS. It was ported from the full-Hermes gateway layer in #30 and ships on PyPI since 0.1.0a2 (install the extension extra).

Gateway messaging E2E (Slack / Discord) uses the context-bound ENC:v3 wire. This is a deliberate breaking change from gateway command/reply v1/v2: deploy a v3-capable Mordred Extension at the same time. Legacy v1/v2 crypto remains available to the WebSocket API and stored-history helpers, but is not accepted as an agent command. See the gateway E2E wire specification.

How it works

The server refuses non-loopback binds and validates the TCP peer, Host, and Origin. It admits only chrome-extension:// / moz-extension:// clients, header-less loopback processes, and its own localhost page. On connect the server sends an auth_challenge; the extension authenticates with its paired ext_token (plus a WebAuthn assertion once a Chromium-extension credential is registered), the localhost page with a per-process page token delivered only in the private launch URL's fragment. The fragment is not sent over HTTP and is removed from browser history before the app starts. Extension WebSocket sessions remain bound to the pairing token generation that authenticated them; re-pairing or clearing pairing state immediately revokes their next privileged frame and discards pending approvals. Firefox transport remains supported, but Firefox WebAuthn registration is refused until the wire protocol carries its browser-specific stable ceremony origin and RP ID. After auth:

For eth_sendTransaction, the extension cannot introduce an arbitrary RPC endpoint or chain: both must match the operator-selected values in ~/.hermes/extension/wallet.json (or the built-in endpoint for that configured chain). RPC transport rejects local/private targets and redirects, pins validated direct DNS answers, and never bypasses the route selected by the network gateway. Before returning any message signature or broadcasting a raw transaction, Hermes recovers its actual signer and verifies that it is still the address shown in the approval prompt.

Wire protocol: the extension repo's SPEC.ja.md §6 / src/lib/protocol.ts; server side in src/mordred_hermes/extension/api.py.

Run it (standalone)

Nothing starts the server automatically yet: Hermes exposes no gateway-boot hook a plugin could use, so register(ctx) cannot launch a long-running server (see docs/dev/ROADMAP.md §"Remaining browser-extension gateway integration"). Until that lands, start it in the foreground with one command — it needs the extension extra (see the extras table above).

PyPI install — include extension; add ethereum for the wallet signing flows shown below (swap macos for keyvault on Linux):

uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 "mordred-hermes[macos,extension,ethereum]==0.1.0a10"

Then use the $M alias from Use it:

$M extension serve      # ws://127.0.0.1:7788/ext — Ctrl+C to stop
# equivalent module form, same --host/--port flags:
~/.hermes/hermes-agent/venv/bin/python3 -m mordred_hermes.extension

From a dev checkout instead:

uv sync --extra extension --extra ethereum
# or: uv pip install -e ".[extension,ethereum]"

.venv/bin/hermes-mordred extension serve      # ws://127.0.0.1:7788/ext — Ctrl+C to stop
.venv/bin/python -m mordred_hermes.extension

Bind failures (port already in use, bad host, privileged port) exit with a one-line error instead of a traceback — see Troubleshooting if you hit a bound-port error. Both Ctrl+C and SIGTERM (systemd, docker stop) shut down cleanly. One divergence between the two forms: with the extension extra missing, only hermes-mordred extension serve prints the install hint — the module form fails on the package import itself with a plain ImportError.

Pairing, auth (incl. Chromium WebAuthn), encrypt/decrypt, history, and the keyvault-backed accounts_request / sign_request flows are fully functional standalone — they only touch ~/.hermes and the keyvault.

Standalone behavior notes

• Chat runs the real agent. serve probes for the Hermes runtime (gateway / run_agent — shipped by the PyPI hermes-agent package, a base dependency) and wires extension/chat.py:make_gateway_chat_handler automatically; E2E-encrypted messages are decrypted, answered by the real AIAgent, and re-encrypted reply-in-kind. A stub reply appears only when that runtime is missing — the startup log names which handler was wired.
• Pairing works end-to-end: run hermes-mordred extension pair in a second terminal while extension serve is running — both sides share ~/.hermes/extension/pending.json, so codes are also consumable by a full Hermes gateway hosting the WS server.
• The private Web page: URL printed by extension serve opens the bundled localhost web app — use the complete URL including its #token=… fragment; a plain anonymous GET serves only the token-free shell. The extension's WS endpoint is /ext. A 503 "web app not built" response appears only if the bundled page is missing — the PyPI wheel ships it.

Install (development)

Canonical dev flow: editable install into the Hermes-managed venv (see setup.md for the full environment build):

# from this repo's root; add ".[macos]" on macOS
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 -e .

Refresh a non-editable live venv. If the live venv holds a wheel instead of the editable install above — the PyPI wheel, or a prior repo build — repo edits do not reach the hermes-mordred binary until you rebuild and reinstall it from the repo root:

uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 --reinstall --no-deps .

--reinstall is required whenever the version string is unchanged (two builds both reporting the same version, say): without it uv treats the requirement as already satisfied and no-ops, leaving the binary on stale code — the symptom is a newly added flag such as configure --with-hermes-setup failing with unrecognized arguments. --no-deps keeps the live editable hermes-agent checkout untouched. Re-run the same command if Hermes rebuilds its venv and drops the wheel.

Local checks run from the repo's own uv-managed venv and mirror the CI test job (HERMES_HOME keeps the tests away from your real ~/.hermes):

uv sync --all-extras                # one-time: builds .venv from uv.lock

uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy
HERMES_HOME=/tmp/hermes-mordred-test-home uv run pytest

The default suite is hermetic — integration tests (-m integration) are excluded and opt back in per suite:

• Tor: hermetic Docker-based integration-tor job in CI (ci.yml).
• Keyvault live hardware: MORDRED_KEYVAULT_LIVE=1 pytest -m integration tests/integration/test_keyvault_macos.py
• Live VPN: MORDRED_LIVE_VPN_TEST=1 MORDRED_MULLVAD_ACCOUNT=… pytest -m integration tests/integration/test_vpn.py (also available as the workflow_dispatch-only integration-vpn.yml job)

Both live suites were last validated on real devices on 2026-05-25.

Releases are cut via the release.yml workflow (PyPI Trusted Publishing); bump versions in lockstep with tools/bump_version.py. Runbook: CI.md.

Troubleshooting

Upgrading

Two different things go by "upgrade": the installed package, and your existing config (Mordred / OpenClaw settings).

Upgrade the installed package

Same command as Install, with the version bumped — a different pinned version is never "already satisfied", so this reinstalls in place without needing --upgrade:

# macOS
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 "mordred-hermes[macos]==<new-version>"

# Linux
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 "mordred-hermes[keyvault]==<new-version>"

Check PyPI (or the badge at the top of this file) for the latest version. Prefer not to pin?

uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 --upgrade "mordred-hermes[macos]"

This resolves to the newest pre-release without extra flags — every release is currently a pre-release, so the all-prereleases fallback applies (see Install above; the same goes for plain pip, if your venv has it — the reference setup's venv ships without one).

Migrate config with hermes-mordred upgrade

Different command, different job: $M upgrade is an idempotent migration of an existing Hermes / OpenClaw setup onto Mordred's config.yaml conventions — it back-fills the plugins.mordred_privacy_check section if it's missing, no-ops if it already matches Mordred's defaults, and auto-detects and migrates a legacy ~/.openclaw install. Safe to re-run.

$M upgrade
$M upgrade --non-interactive --policy-conflict keep-existing

See USAGE.md — upgrade for the full flag reference (--reset, --audit-merge, --policy-conflict). Setting up fresh instead of migrating an existing install? Use configure (above), not upgrade.

Uninstall

Reverse the setup in the order below.

⚠️ Decrypt before you remove anything. If you turned on at-rest encryption, uninstalling the package or deleting the key first leaves your .env, config, and memory permanently unreadable. Run step 1 while the CLI and key are still present.

M=~/.hermes/hermes-agent/venv/bin/hermes-mordred

1. Decrypt everything back to plaintext.

$M encryption disable all        # env / config / memory / workspace → plaintext
$M vault disable-config-decrypt  # stop transparent config decrypt, restore plaintext config.yaml
$M encryption status             # verify — every row reads [off]

2. Destroy the key material — optional and irreversible. Skip it if you plan to reinstall and keep the same vault.

$M keyvault reset --yes          # DESTROY profile-owned wrapping keys + remove the keyvault dir

Current profile-scoped keys are deleted. Legacy machine-global keys are retained when exclusive ownership cannot be proven; export a backup before reset and follow the migration guidance in docs/user/USAGE.md.

3. Disable the plugins. Remove the six mordred_* entries from the plugins.enabled list in ~/.hermes/config.yaml (undo Enable the plugins).

4. Uninstall the package from the Hermes venv. This also removes the config-decrypt .pth bootstrap from site-packages.

uv pip uninstall --python ~/.hermes/hermes-agent/venv/bin/python3 mordred-hermes
# or, if the venv ships pip:
~/.hermes/hermes-agent/venv/bin/pip uninstall mordred-hermes

5. Remove leftover state — optional, and only after step 1 (the vault lives here):

rm -rf ~/.hermes/mordred/        # audit log, policy, credentials, tor-data, keyvault

Also delete any MORDRED_* entries you added to ~/.hermes/.env. If you ran keyvault enable-se / enable-tpm, the built helper is not removed by the steps above — delete it by hand (default location, unless you set MORDRED_SEKEY_INSTALL_DIR / MORDRED_TPMKEY_INSTALL_DIR):

rm -f ~/.local/bin/mordred-hermes-sekey    # macOS Secure Enclave helper
rm -f ~/.local/bin/mordred-hermes-tpmkey   # Linux TPM 2.0 helper

Repository layout

src/mordred_hermes/    the Mordred entry-point plugins + shared internals
native/                hardware-key helper sources, shipped in the wheel and built
                       on demand by `keyvault enable-se` / `enable-tpm`:
                         sekey-helper/  — Swift, Secure Enclave (macOS)
                         tpmkey-helper/ — Rust, TPM 2.0 (Linux)
skills/mordred-status/ read-only conversational status skill for the agent
packaging/             config-decrypt .pth bootstrap; PyPI name-reservation stub
scripts/               offline verification-digest tool for `keyvault init`
tools/                 dev tooling (version bump, hook-payload drift check)
tests/                 hermetic unit suite + opt-in tests/integration/
docs/                  user and developer documentation (see below)

Documentation

More under docs/dev/: PLAN, TODO, ROADMAP, PATHS, MIGRATION, HARNESS_PRIVACY, HOOK_PAYLOADS.

License

MIT