# Domani for Hermes Agent

Give a Hermes agent its own mailbox, receive email through authenticated
webhooks, and manage domains and DNS through Domani's MCP tools.

This is a portable [Agent Plugins v1](https://agentplugins.org/) package. It
contains declarative skill instructions and a local stdio MCP bridge; it does
not execute plugin Python code.

## Requirements

- Hermes Agent `0.20.5` or newer
- Node.js with `npx` available
- Network access to `domani.run` and the npm registry on first launch

## Install

Review `plugin.json`, `mcp.json`, and the skill safety rules first. Then install
the package disabled and explicitly enable it:

```bash
hermes plugins install gwendall/hermes-domani --no-enable
hermes plugins list
hermes plugins enable domani
```

Hermes 0.20.5 is the first tagged release with the portable Agent Plugins v1
loader used by this package. Restart Hermes after enabling the plugin.
Production deployments can pin the
exact release commit with `--ref <40-character-commit-sha>`; use the commit
attached to the [latest release](https://github.com/gwendall/hermes-domani/releases/latest).

## Authenticate without exposing a token

Run the pinned Domani CLI login yourself:

```bash
npx -y domani-cli@0.4.49 login
```

Approve access in the browser. The CLI stores the credential in the operating
system keychain when available. The MCP bridge reads it in memory and forwards
requests to Domani's hosted Streamable HTTP endpoint. Do not paste a token into
Hermes, `mcp.json`, a prompt, shell arguments, or repository files.

## Prove the email loop

First ask Hermes:

> Use Domani to create my free @domani.run inbox, report its address, then stop
> before configuring a secret-bearing webhook.

If the receiver requires `Authorization`, configure and test it yourself in a
local terminal. Replace the address and URL, but keep the value out of the
command line and model context:

```bash
read -rsp 'Webhook sender key: ' HERMES_WEBHOOK_KEY; echo
export HERMES_WEBHOOK_AUTH="Bearer $HERMES_WEBHOOK_KEY"
npx -y domani-cli@0.4.49 email webhook agent@domani.run \
  --url 'https://your-receiver.example/inbound' \
  --authorization-env HERMES_WEBHOOK_AUTH
npx -y domani-cli@0.4.49 email webhook-test agent@domani.run
unset HERMES_WEBHOOK_KEY HERMES_WEBHOOK_AUTH
```

Use `--api-key-env` instead when the destination expects `X-API-Key`. Domani
encrypts supported header values at rest and never returns them from the API.
After the test passes, send one real email to the new address and verify the
destination receives it.

## What enabling grants

Hermes correctly treats plugins as full-trust input. This package grants:

| Surface | What it does |
|---|---|
| Skill | Adds Domani workflow and safety instructions to Hermes |
| MCP process | Runs `npx -y domani-cli@0.4.49 mcp serve` without a shell |
| Network | Connects the bridge to Domani and downloads the pinned CLI if absent |
| Credential | Lets the bridge ask the OS keychain for the logged-in Domani credential |
| Mutations | Exposes only the tools returned for the current account and entitlements |

The plugin declares no token, MCP `env`, HTTP header, hook, native executable,
or writable repository path. Domani tools may still send mail, change DNS,
purchase or transfer domains, and delete resources. The bundled skill requires
explicit confirmation immediately before financial, destructive, external-send,
ownership, permission, broad DNS, or secret-reveal operations.

## Update and uninstall

```bash
hermes plugins update domani
hermes plugins disable domani
hermes plugins remove domani
```

Updates replace package-owned instructions and MCP configuration. They do not
delete your Domani account or keychain credential. To disconnect Domani fully,
also run `npx -y domani-cli@0.4.49 logout` after removing the plugin.

## Verify the package

```bash
node scripts/validate.mjs
```

Product guide: https://domani.run/integrations/hermes-agent

Hermes plugin guide: https://hermes-agent.nousresearch.com/docs/developer-guide/plugins