Connect Hermes

Hermes keeps its model and its session. The file tools it reaches through Chio answer to the kernel: each call is admitted before the tool runs, and each decision is signed into a receipt in your project.

In Hermes's configuration, Chio is a stdio MCP server named chio that starts the filesystem server behind it under the code-agent preset. That route needs no plugin. The chio toolset plugin is the second route, admitted by a Chio sidecar.

1. Register Chio as an MCP server in Hermes

Add a chio entry to ~/.hermes/config.yaml and merge it with the servers you already have. Replace each YOUR_PROJECT_PATH with the absolute path the first step prints.

The test lists six tools on server fs, the ones the preset grants: read_file, list_directory, search_files, write_file, edit_file, and create_directory. A listed tool runs only after the kernel admits the call Hermes makes to it.

2. List and read your project through the kernel

Write a small file into the project, then restart Hermes so it loads the saved configuration.

printf '%s\n' 'Hello from Hermes.' > chio-example.txt
hermes chat

Use the chio MCP server to list the project directory, then read chio-example.txt.

Hello from Hermes.

You should see the names in the directory you configured, then the sentence you wrote. Both calls went through the kernel before the filesystem server ran them.

3. Find the listing and the read in chio-receipts.db

The kernel signed one receipt per decision into that database, beside your project files.

chio --receipt-db chio-receipts.db receipt list \
  --admin-all --tool-server fs \
  | jq -r '[.decision.verdict, .tool_name, .id] | @tsv'

allow   list_directory   rcpt-01b4…2c71
allow   read_file        rcpt-01b4…3e08

You should see the listing and the read, each as allow with its receipt id. Pass an id to chio receipt explain, with the same database and --admin-all, to see the grant and the checks behind it.

Hermes reaches the kernel by one of two routes

The MCP server governs the filesystem tools Chio launches. The plugin adds its own governed toolset, admitted by a Chio sidecar under a capability you mint.

Either route governs the tools it serves. Hermes's built-in tools, and any tool you select outside the route, keep their own path.

Add the chio toolset as a Hermes plugin

The chio-hermes plugin registers chio_file_read, chio_file_write, chio_file_edit, chio_file_list, chio_file_search, chio_shell_run, and six git tools: chio_git_status, chio_git_diff, chio_git_log, chio_git_add, chio_git_commit, and chio_git_run. Install it into Hermes's own Python environment from the plugin source.

Mint a capability, then read a file through the sidecar

Point the plugin at your Chio sidecar and mint a capability for the fs tool server. The subject is the agent's Ed25519 public key, in hex; the capability lasts 3,600 seconds unless you pass --ttl.

export CHIO_SIDECAR_URL=http://127.0.0.1:9090
AGENT_KEY=9f2c…71ab   # the agent's Ed25519 public key, in hex
hermes chio issue --subject "$AGENT_KEY" --tool-server fs

capability issued: cap-01b7…4d2a
  subject:       9f2c…71ab
  tool servers:  fs
  ttl seconds:   3600

  export CHIO_CAPABILITY_ID=cap-01b7…4d2a

Set the printed capability, the workspace root, and a file to read in the same environment that starts Hermes. Then open a chat with the chio toolset enabled.

export CHIO_CAPABILITY_ID=cap-01b7…4d2a
export CHIO_WORKSPACE_ROOT="$PWD"
printf '%s\n' 'Hello from Hermes.' > chio-example.txt
HERMES_PLUGINS_DEBUG=1 hermes chat -t chio,hermes-cli

Use chio_file_read to read chio-example.txt.

Hello from Hermes.

You should see the file's sentence. The sidecar admitted the chio_file_read call under CHIO_CAPABILITY_ID and recorded its receipt. A call after the capability lifetime returns chio_capability_expired; mint a new one with hermes chio issue. A call with no capability set returns chio_not_configured.

Next: query and verify what Hermes did