# Add nmbr to Hermes Agent

> The nmbr platform adapter for Hermes Agent — three files in ~/.hermes/plugins/nmbr/ and your Hermes agent has a number.
>
> Markdown mirror of https://nmbr.ai/developers/docs/quickstart-hermes/ — part of the nmbr Agent API docs (https://nmbr.ai/developers/docs/). Spec: https://nmbr.ai/developers/openapi.yaml · Site index: https://nmbr.ai/llms.txt

**[Beta]** Chat round-trip, typing and the fail-closed `/approve` flow are verified end-to-end inside a real Hermes gateway (0.19.0, macOS). v0.2 adds native approval cards (tap Approve / Reject on the phone), unit-tested against Hermes' approval registry and awaiting its first live run. If something breaks, tell us at [support@nmbr.ai](mailto:support@nmbr.ai?subject=nmbr%20Hermes%20adapter) with the version and the error.

Requires Hermes Agent ≥ 0.19 on Python 3.11–3.13 (on Python 3.14, pip silently resolves an old Hermes — install with `pipx install --python python3.13 hermes-agent`), plus a configured model provider (`hermes model`). The adapter depends only on `httpx`, which Hermes ships.

## Add nmbr to Hermes

1. In the nmbr app: **Agents → Yours → Create an agent**. Copy the token (shown once).
2. Install the adapter (three files into `~/.hermes/plugins/nmbr/`):
   ```bash
   curl -fsSL https://nmbr.ai/developers/hermes/install.sh | sh
   ```
3. Enable the plugin (Hermes quarantines user-installed plugins until you opt in), answering **No** to the tool-override question — a messaging adapter never needs that privilege:
   ```bash
   hermes plugins enable nmbr
   ```
4. Enable the platform, and keep approvals interactive, in `~/.hermes/config.yaml`:
   ```yaml
   platforms:
     nmbr:
       enabled: true
   approvals:
     mode: manual   # without this, "smart" approval may auto-approve flagged commands
   ```
5. Run it in the foreground (`hermes gateway start` runs as a launchd service and won't see your shell's env vars — for service mode put the token in `platforms.nmbr.extra.token` instead):
   ```bash
   NMBR_AGENT_TOKEN=agent:… NMBR_ALLOWED_USERS=123-456-789 hermes gateway run
   ```
6. Open the chat with your agent in nmbr and say hi.

## What you get

- **Two-way chat** with typing indicators and progress notes for long turns; voice notes arrive as their transcript, a moment after the note (the plugin waits for it).
- **Approvals, fail-closed — as native cards** (v0.2): when a command trips Hermes' dangerous-command detector, an [approval card](/developers/docs/approvals/) appears in the nmbr chat with the command and Hermes' reason. Tap **Approve** to run it once, **Edit** the card's `scope` to `"session"` or `"always"` first to remember the pattern, or **Reject**. Only the person in that 1:1 can decide. The card lives as long as Hermes waits (`approvals.timeout`, default 60 s) — a later tap gets "too late" and nothing runs. `/approve` / `/deny` still work, and Hermes falls back to its text prompt if the card can't be sent. Requires `approvals.mode: manual` (step 4).
- **Who can talk to the agent**: `NMBR_ALLOWED_USERS` is a list of nmbrs (`NMBR_ALLOW_ALL_USERS=true` trusts every contact who added the agent). nmbr itself already limits senders to contacts.
- **Cron and notifications** reach your phone via `NMBR_HOME_CHANNEL` (or reply `/sethome` in the chat), even when the gateway isn't running.

| Env | Meaning |
|---|---|
| `NMBR_AGENT_TOKEN` (required) | The agent token |
| `NMBR_BASE_URL` | API base, default `https://nmbr.ai/api` |
| `NMBR_ALLOWED_USERS` / `NMBR_ALLOW_ALL_USERS` | Who may talk |
| `NMBR_HOME_CHANNEL` / `_NAME` | Cron / notification target |

Files: [`plugin.yaml`](/developers/hermes/plugin.yaml) · [`adapter.py`](/developers/hermes/adapter.py) · [`__init__.py`](/developers/hermes/__init__.py) · [`install.sh`](/developers/hermes/install.sh) · [README](/developers/hermes/README.md)