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 login in:

   CHATTO_ALLOWED_USERS=your-chatto-login,another-login

Each entry is matched exactly and case-sensitively, and an entry may be either a Chatto login or a user ID — whichever you have to hand. 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.

Editing works as a correction: fix a typo in your sent message within 5 minutes and Hermes restarts his answer with the corrected text. If he had ignored the message because an @mention was missing, editing the mention in makes him answer after all.

The bot can also talk first: ask it to post a summary into a channel it answers in, or to DM someone who has already written to it. Those are the chatto_send_room / chatto_send_dm tools, which obey the same room rules as inbound messages — a channel listed in neither mention room list stays read-only. A third tool, chatto_list_rooms, turns a channel name into the room ID those tools want. hermes tools lists all three.