agentvault-hermes

agentvault-hermes

Native AgentVault plugin for the Hermes agent runtime by Nous Research.

End-to-end encrypted, zero-knowledge messaging between AI agent owners and their Hermes agents, plus A2A discovery + messaging across other AgentVault-enabled frameworks.

Quickstart

The setup flow mirrors the OpenClaw plugin's: create an invite via the AgentVault web app, enroll the device from the CLI, approve in the web UI, and the plugin auto-activates.

1. Install the package

uv tool install "agentvault-hermes[mls]"

(Or pip install "agentvault-hermes[mls]" directly into the Hermes gateway venv.)

The [mls] extra is required — it pulls agentvault-mls-rs-uniffi, the compiled MLS crypto core. Without it the agentvault-hermes CLI fails to start at all (ModuleNotFoundError: mls_rs_uniffi). Pre-built wheels mean no Rust toolchain is needed.

uv tool install puts the agentvault-hermes CLI on your PATH in its own venv. The first agentvault-hermes setup call below also auto-installs the plugin into the Hermes gateway venv — the venv Hermes actually loads plugins from — so you don't have to think about the two-venv layout.

2. Create an invite at agentvault.chat

1. Log in to https://agentvault.chat.
2. Open My Agents → Quick Add (or /agents/quick-add).
3. Enter an agent name and click Create.
4. The web UI displays a CLI command containing your invite token. The token is the part after --token=. Copy that.

3. Run the Hermes setup command on your machine

agentvault-hermes setup --token=<paste-the-token>

The plugin will:

• check your environment (hermes binary, ~/.hermes/config.yaml)
• detect any OpenClaw coexistence and pick a non-colliding port
• generate Ed25519 + X25519 + MLS init keys
• POST /api/v1/enroll to the AV backend (your device is now PENDING)
• wait for you to approve in the web UI

4. Approve the device in agentvault.chat

The web UI's pending-device card auto-detects your enrollment. Click Approve and Chat. The CLI is polling /api/v1/devices/{id}/status and will see the change within ~3 seconds.

5. Plugin finishes automatically

After approval, the plugin:

• POSTs /api/v1/devices/{id}/activate to receive the device JWT
• writes ~/.hermes/agentvault/<account>/state.json (mode 0o600)
• adds an agentvault MCP server entry to ~/.hermes/config.yaml (a timestamped backup of the original is written next to it)

6. Start the Hermes gateway

[!IMPORTANT] This step is required. Running the hermes TUI alone only registers plugins — it does NOT activate the AgentVault gateway platform that opens the WebSocket to AgentVault. Without a running gateway, your agent appears Offline in agentvault.chat indefinitely even though enrollment succeeded.

Pick one:

Foreground (recommended for first run / debugging):

hermes gateway run

You'll see ✓ agentvault connected once the WS handshake completes. Ctrl-C to stop. Logs land in ~/.hermes/logs/agent.log and ~/.hermes/logs/errors.log.

Background (launchd / systemd service):

hermes gateway install
hermes gateway start

This installs a persistent service that auto-starts on login. Check status with hermes gateway status; stop/restart with hermes gateway stop / hermes gateway restart.

7. Verify

agentvault-hermes doctor

Reports green on three checks:

• Configuration — state.json exists with a valid JWT
• Connectivity — AV backend reachable
• OpenClaw coexistence — neighbor framework detected (or not)

The doctor command does NOT yet verify the gateway is running — tracked as a follow-up. For now confirm via hermes gateway status (or by sending a message from agentvault.chat and seeing the reply land).

Troubleshooting

Upgrading agentvault-hermes

uv tool install --upgrade "agentvault-hermes[mls]"
agentvault-hermes doctor    # (or any agentvault-hermes command — auto-syncs the gateway venv)
hermes gateway restart      # picks up the new code

Any agentvault-hermes command runs a pre-flight that keeps the Hermes gateway venv in sync with the version on your PATH. If the pre-flight ever fails (e.g., offline), agentvault-hermes doctor reports the drift explicitly with the exact pip command to heal manually.

"I sent a message in agentvault.chat but the agent never replies"

99% of first-run reports are a missing Step 6. Run hermes gateway status — if it says not running, start it with hermes gateway run (foreground) or hermes gateway start (background service).

The TUI's hermes and hermes chat commands intentionally do NOT start the gateway — they're chat surfaces, not daemon launchers. The WebSocket that delivers your inbound messages to the agent runtime lives in the gateway daemon process, not the TUI.

"Agent shows Offline in agentvault.chat even with the gateway running"

Check ~/.hermes/logs/agent.log for the AV adapter connected: account=... line. If absent, the gateway either crashed at startup or never tried to activate the platform. Common causes: stale state.json (re-enroll), wrong API base URL in ~/.hermes/agentvault/<account>/state.json, or a backend pairing already mapped to a different device (delete the agent in AV-web and re-enroll a fresh device).

Re-enrolling

state.json makes setup idempotent — re-running agentvault-hermes setup with state.json present is a no-op. To re-enroll (new invite, new device record):

rm ~/.hermes/agentvault/default/state.json
agentvault-hermes setup --token=<new-token>

Invite tokens are single-use, so each re-enrollment requires a fresh invite from the web UI.

Multi-account

agentvault-hermes setup --account=alice --token=<token-1>
agentvault-hermes setup --account=bob   --token=<token-2>

Each account gets its own ~/.hermes/agentvault/<account-id>/ subdirectory with separate keys and JWT.

Status

This package is in active development. Phase 0 (mls-rs interop spike), Phase 1 (foundation: identity, transport, CLI, integration tests, CI), and Phase 2 (MLS crypto core) have shipped on main. Phase 3 (full encrypted send/receive over the live transport) is next.

Phase 2 capabilities (shipped)

The crypto module under src/agentvault_hermes/crypto/ is feature-complete for the four primitives Hermes needs and is byte-compatible with the OpenClaw plugin's TypeScript implementation where mathematically possible.

Cross-module flows (X3DH → DR bootstrap, MLS multi-member lifecycle, state save/reload, telemetry hooks) are exercised in tests/integration/test_crypto_*.py.

The Phase 2 acceptance smoke at tests/integration/test_phase2_demo.py is the runnable summary — it imports every public crypto surface and walks through the four primitives in one test. When that file fails, expect a packaging-level break; localized regressions surface in the deeper test suites listed above.

To run only the Phase 2 acceptance demo:

cd packages/plugin-hermes
uv run pytest tests/integration/test_phase2_demo.py -v

To run the full Phase 2 suite (~210 tests, runtime ~2s, includes 9 documented xfails for cross-impl bridges that land in WS-25 follow-up and Phase 6 telemetry):

uv run pytest tests/ -v

Plans + design docs

See in the AgentVault repo:

• docs/plans/2026-05-05-hermes-native-integration-design.md — original design.
• docs/plans/2026-05-05-hermes-native-integration-phase0-1-implementation.md — Phase 0/1 implementation plan.
• docs/plans/2026-05-07-hermes-phase2-implementation.md — Phase 2 work-stream breakdown (WS-22 through WS-27).