# nmbr for Hermes Agent

> **Beta.** This plugin is new and has been tested against the framework's SDK and a real nmbr server, but not yet by many people inside the framework itself. If something breaks, please tell us at support@nmbr.ai (include the version and the error) — fixes ship fast.


**Give your Hermes agent a number.** This platform adapter connects [Hermes Agent](https://hermes-agent.nousresearch.com) to [nmbr](https://nmbr.ai): your agent gets an `800-xxx-xxx` nmbr and you talk to it from the nmbr app on your phone — replies, typing indicators, cron deliveries and fail-closed approvals, from any machine with outbound internet (no public URL, no webhook).

## Add nmbr to Hermes in 2 minutes

1. In the nmbr app: **Agents → Yours → Create an agent**. Copy the agent token (shown once).
2. Install the adapter (two files into `~/.hermes/plugins/nmbr/`):
   ```bash
   sh install.sh            # from this directory, or:
   mkdir -p ~/.hermes/plugins/nmbr && cp plugin.yaml adapter.py ~/.hermes/plugins/nmbr/
   ```
3. Configure and run:
   ```bash
   hermes gateway setup     # pick nmbr, paste the token, add your own nmbr to allowed users
   hermes gateway start
   ```
   or with env vars: `NMBR_AGENT_TOKEN=agent:… NMBR_ALLOWED_USERS=123-456-789 hermes gateway start`.
4. Open the chat with your agent in nmbr and say hi.

## What you get

- **Two-way chat** — nmbr messages become Hermes turns; replies go back to the same 1:1. Voice notes arrive as their transcript; images/documents as tagged text (v0.1).
- **Typing indicator** while the agent works.
- **Approvals, fail-closed** — Hermes' dangerous-command prompt is delivered into the nmbr chat; answer `/approve`, `/always` or `/cancel` there. Only an allowed sender can answer.
- **Who can talk to the agent** — `NMBR_ALLOWED_USERS` (nmbrs). nmbr itself already limits senders to people who *added your agent as a contact*; `NMBR_ALLOW_ALL_USERS=true` trusts all of them.
- **Cron / notifications** — set `NMBR_HOME_CHANNEL` to your nmbr; `deliver=nmbr` jobs and `send_message` reach you even when the gateway isn't running (standalone sender).

## Config reference

| Env | config.yaml `platforms.nmbr.extra` | Meaning |
|---|---|---|
| `NMBR_AGENT_TOKEN` (required) | `token` | The agent token (`agent:…`) |
| `NMBR_BASE_URL` | `base_url` | API base, default `https://nmbr.ai/api` |
| `NMBR_ALLOWED_USERS` | — | Comma-separated nmbrs allowed to talk |
| `NMBR_ALLOW_ALL_USERS` | — | `true` = every contact who added the agent |
| `NMBR_HOME_CHANNEL` / `_NAME` | `home_channel` | Cron/notification target (your nmbr) |

Requires Hermes Agent ≥ 0.20 (Python ≥ 3.11); depends only on `httpx`, which Hermes already ships. Tests: `python -m pytest` (uses a stubbed Hermes runtime and a mocked Agent API).

## Roadmap

- v0.2: native nmbr approval cards (Approve / Edit / Reject on the phone) for `send_exec_approval`, plus clarify buttons.
- Media in and out.