hermes-chatto-plugin/after-install.md

Chatto Plugin Installed ✅

During installation you were prompted for the Chatto connection details, and your answers were written to ~/.hermes/.env. Next steps: review that configuration — including who the bot is allowed to answer, which is off by default — restart the gateway so it comes online, then bring it into a room and try it out.

Review your ~/.hermes/.env or config.yaml. Secrets (passwords, tokens) belong in ~/.hermes/.env only — never in config.yaml; non-secret settings can live in either file. Environment variables take precedence over config.yaml entries.

1. Connection details (required)

Your Chatto bot token (an API key like cht_BK_...):

   CHATTO_TOKEN=your-bot-key

Generate one in Chatto under Settings → Bot Accounts.

Without CHATTO_BASE_URL the plugin connects to the public ChattoHQ server (https://chat.chatto.run). To use your own server:

   CHATTO_BASE_URL=https://chat.example.com

1. Home channel (optional)

Where cron job output and notifications get delivered when there is no conversation context to reply into — the default outbound target, nothing more. It follows the same participation rules as any room: a silent room stays quiet, so list it in one of the mention room lists (see step 6) too if the bot should also converse in it. If unset, context-less deliveries have no Chatto target and are not sent — set one if you plan to use Hermes' proactive output:

   CHATTO_HOME_CHANNEL=ROOM_ID_HERE

1. Who the bot answers (required unless you open it up)

The bot replies only to the Chatto users you name here. If the installer left this empty, it answers nobody — not even you. Put your own Chatto user ID in (the U… string identifying your account, not your login name — see README.md, "How to find a user ID", for how to get one):

   CHATTO_ALLOWED_USERS=UYourUserIDHere,AnotherUserID

Each entry is matched exactly and case-sensitively, and must be a user ID — a login name in the list does not authorize anyone. To open the bot to every user on the server instead, use CHATTO_ALLOW_ALL_USERS=true — which hands all of them the agent's capabilities, including tool use, so keep that for a trusted, private server. Setting both is rejected as conflicting.

1. Restart the Hermes Gateway

The bot comes online here, and it picks up everything above from .env right now — a change made after this restart counts only from the next one. The steps below need it running:

   hermes gateway restart

1. Add the bot to a room

The bot can see more rooms than it has joined, but it answers and posts only in rooms its account is a member of. Membership lives on the Chatto server, survives gateway restarts, and nothing is joined silently on startup. Invite the bot account natively in Chatto, or DM it:

   /join ROOM_ID_HERE

1. Test

Send any message in a room the bot has joined — as one of the users from step 3, since everyone else is ignored. DMs answer right away; every other room stays silent until you list it — in CHATTO_REQUIRE_MENTION_ROOMS (answers only when the message addresses the bot via @name, @all or @here) or CHATTO_OPTIONAL_MENTION_ROOMS (answers every message). The /join reply prints both lines ready to paste, with the room ID filled in.

That is the first-run path done. Everything beyond answering a message — corrections by editing, the plugin tools, and server-side prerequisites such as message search — is in README.md.