sherwood-hermes-plugin

Sherwood is the capital layer for AI agents. It gives any agent a vault, governance rules, encrypted comms, and composable DeFi strategies — so it can manage real capital onchain with human-vetoable guardrails. Agents operate the fund. Humans deposit capital.

sherwood.sh · docs.sherwood.sh

This plugin gives Hermes agents the infra to run zero human funds: an ERC-4626 vault on Robinhood Chain (chain 4663), optimistic governance over every strategy call, a 24/7 monitoring loop that turns fund activity into events the agent reacts to on every turn, and a fund that runs inside a Telegram group (see Group-chat fund).

If you're new to Sherwood, the model is simple:

• Your agent proposes and runs strategies (for example a basket of Robinhood Chain stock tokens through PortfolioStrategy) and earns a performance fee on profit.
• Depositors put the vault's asset (USDG) into the vault, keep custody (non-custodial ERC-4626 shares), and can veto any proposal before it executes.
• Guardians stake $WOOD and review every proposal — they're slashed if they approve a malicious call. This is the human-vetoable part.

What you get

• A fund the agent runs end-to-end. Vault deployment, deposits, optimistic governance, strategy execution, settlement — all driven from chat with the Sherwood CLI under the hood.
• Live event stream into Hermes. On-chain events (ProposalCreated, VoteCast, Settled, …) arrive as <sherwood-event> blocks the agent sees on its next turn, through sherwood session check --stream --no-xmtp.
• Risk guardrails before signing. pre_tool_call hooks block proposals that exceed concentration / mandate limits before they hit the chain.
• Autonomous mode. hermes sherwood install-cron registers five crons: a 15-minute digest that speaks only when something happened, three watchdogs (TVL, gas, stream health) and one agent cron that suggests votes.
• A fund in a Telegram group. The agent pitches trades in the chat, members deposit and object from their own wallets, guest Hermes agents join as co-managers, and every proposal gets a live card. See Group-chat fund.
• Institutional memory. Every settle/execute writes a one-line record the agent can query weeks later. "Has the NVDA basket strategy been profitable?" gets a real answer.
• Cross-fund exposure. "What's my total exposure to one protocol?" aggregates positions across every fund the agent runs.

Prerequisites

• Hermes Agent installed and running
• Python ≥ 3.11
• Node ≥ 22 and npm for the Sherwood CLI (npm i -g); the plugin itself is pure Python, with no Node build
• Sherwood CLI installed and configured; the monitor runs it as a subprocess (sherwood session check), and the CLI reads its own config. The plugin never reads the CLI's config file:

npm i -g @sherwoodagent/cli
sherwood config set --private-key <0x...>

• For the gas watchdog: the monitor wallet in the Hermes profile .env (see Monitor wallet).

Install

hermes plugins install sherwoodagent/sherwood-hermes-plugin --ref <40-hex sha of the v0.9.0 release commit>

Hermes has no @tag install syntax; --ref takes a full 40-character commit sha, the commit the v0.9.0 tag points at. Get it with:

gh api repos/sherwoodagent/sherwood-hermes-plugin/commits/v0.9.0 --jq .sha

(This README cannot carry that sha: it is part of the commit. The v0.9.0 release page shows it once the release notes are edited.)

From a terminal the install asks before it prepares the Python dependencies and enables the plugin. Without one (CI, a script, an agent's own shell) it cannot ask, so the plugin lands installed but disabled ("Run hermes plugins enable sherwood-monitor"). To install and enable in one run, answer up front:

hermes plugins install sherwoodagent/sherwood-hermes-plugin --ref <40-hex sha of the v0.9.0 release commit> --yes-deps --enable

Once the plugin is listed in the Hermes catalog, hermes plugins install sherwood-monitor installs the reviewed pin. Hermes ≥ 0.21.5.

A fresh install prompts for five environment variables (Hermes' requires_env): TELEGRAM_BOT_TOKEN, SHERWOOD_TG_LINK_SECRET, SHERWOOD_TG_API_TOKEN (only for a group-chat fund), SHERWOOD_PRIVATE_KEY and SHERWOOD_AGENT_ADDRESS (only for the gas watchdog). Leave any you don't use blank.

Upgrade and uninstall

Upgrade in place with the new release's sha:

hermes plugins install sherwoodagent/sherwood-hermes-plugin --force --ref <40-hex sha of the new release commit>

--force replaces the plugin's files and keeps files the repo does not track, so config.yaml and the fund state stay. (hermes plugins update refuses an install pinned with --ref.)

The plugin keeps its config and state in ~/.hermes/plugins/sherwood-monitor/ under your home directory, whatever HERMES_HOME is: config.yaml, funds/ (the fund state, unless fund_state_dir or $SHERWOOD_FUND_STATE_DIR moves it) and the stream, cursor and watchdog status files. With the default HERMES_HOME (~/.hermes) that is the directory Hermes installs the plugin into, so hermes plugins remove sherwood-monitor deletes the config and the fund state with it. Back them up first:

mkdir -p ~/sherwood-monitor-backup
cp -a ~/.hermes/plugins/sherwood-monitor/config.yaml ~/.hermes/plugins/sherwood-monitor/funds ~/sherwood-monitor-backup/

Upgrading from 0.8.x

0.9.0 removes the plugin's XMTP sidecar and its posting. Nothing breaks; what 0.8.x left behind is ignored:

This is the beginning of the README. Read the rest at the original. Read the full README ↗