Hermes Agent IRC — Classic Chat Protocol Setup

IRC — Classic Chat Protocol

If you’ve been around the internet for a while, you know IRC. It’s the granddaddy of chat protocols — plain text, no frills, and still going strong on networks like Libera.Chat. And now, Hermes can hang out there too.

The IRC adapter connects Hermes to any IRC server and relays messages between a channel (or direct messages) and your agent. The best part? It’s built entirely on Python’s standard asyncio library — no external dependencies, no SDK, no daemon. Just pure, classic chat.

What to expect (and what not to)

IRC is text-only. There’s no voice, no images, no file sharing, no threads, reactions, or typing indicators. Replies come back as plain PRIVMSG lines, and long messages are automatically split to fit IRC’s line limit. It’s simple, but it works.

💡 Pro tip: Run hermes gateway setup and pick IRC for a guided walkthrough.

What you’ll need

Before you start, make sure you have:

• An IRC server to connect to (e.g. irc.libera.chat)
• A channel to join (e.g. #hermes) — you can comma-separate multiple channels
• A nickname for your bot (default: hermes-bot)
• Optional: a registered nick + NickServ password if your network requires identification

Two ways to configure

You can set up IRC using environment variables (quick and dirty) or the gateway block in ~/.hermes/gateway-config.yaml (cleaner for persistent setups).

Option A — gateway-config.yaml

gateway:
  platforms:
    irc:
      enabled: true
      extra:
        server: irc.libera.chat
        port: 6697
        nickname: hermes-bot
        channel: "#hermes"
        use_tls: true
        server_password: ""       # optional server password
        nickserv_password: ""     # optional NickServ identification
        allowed_users: []         # empty = allow all, or list of nicks
        max_message_length: 450   # IRC line limit (safe default)

Option B — environment variables

Variable	Required	Description
IRC_SERVER	✅	IRC server hostname (e.g. irc.libera.chat)
IRC_CHANNEL	✅	Channel(s) to join — comma-separate for multiple
IRC_NICKNAME	✅	Bot nickname (default: hermes-bot)
IRC_PORT	—	Server port (default: 6697 with TLS, 6667 without)
IRC_USE_TLS	—	Use TLS (true/false; default true on port 6697)
IRC_SERVER_PASSWORD	—	Server password for the PASS command
IRC_NICKSERV_PASSWORD	—	NickServ password for automatic IDENTIFY on connect
IRC_ALLOWED_USERS	—	Comma-separated nicks allowed to talk to the bot
IRC_ALLOW_ALL_USERS	—	Allow anyone in the channel to talk to the bot (dev only)
IRC_HOME_CHANNEL	—	Channel for cron / notification delivery (defaults to IRC_CHANNEL)

Who gets to talk to your bot?

By default, only nicks listed in allowed_users (or IRC_ALLOWED_USERS) can chat with Hermes. If you leave the list empty and set IRC_ALLOW_ALL_USERS=true, anyone in the channel can talk to the bot. That’s handy for testing, but we don’t recommend it on public networks — IRC nicks aren’t authenticated unless the network enforces NickServ.

If your network registers nicks, set IRC_NICKSERV_PASSWORD (or nickserv_password) so the bot identifies itself on connect and keeps its registered nick.

Channels vs. direct messages

• Messages in a joined channel are treated as a group conversation.
• Private messages to the bot are treated as direct messages.

Cron jobs and notifications go to the home channel — IRC_HOME_CHANNEL if set, otherwise the first IRC_CHANNEL.

Fire it up

hermes gateway start

Check the connection status anytime with:

hermes gateway status

IRC connection state is reported there, even for env-only setups.

A couple of final notes

• Long agent replies are automatically split into multiple PRIVMSG lines to stay within IRC’s line limit (max_message_length, default 450 bytes after protocol overhead).
• The adapter locks credentials per server+nick, so two Hermes profiles won’t fight over the same IRC identity.

IRC might be old-school, but it’s reliable, lightweight, and still everywhere. Now your Hermes agent can be too.