Deploy HexBot

Requirements

Node.js 24+pnpmDocker + Compose

Node.js and pnpm for manual install. Docker + Compose for containerized deployment.

Quick Start — Docker

The recommended deployment method. Plugins, config, and data are mounted from the host so you can edit and reload without rebuilding the image.

bash

git clone https://github.com/jstnmthw/hexbot
cd hexbot
cp config/bot.example.json config/bot.json
cp config/plugins.example.json config/plugins.json
# edit config/bot.json with your IRC server and credentials
docker compose up -d
docker compose logs -f

DCC CHAT ports 49152-49171 are exposed by default.

Manual Install

bash

git clone https://github.com/jstnmthw/hexbot
cd hexbot
pnpm install
cp config/bot.example.json config/bot.json
cp config/plugins.example.json config/plugins.json
# edit config files
pnpm start          # production, no REPL
pnpm dev            # development, with interactive REPL

Configuration

Two JSON files control the bot. Both are ignored by git — only the example files are committed.

config/bot.json

IRC server, credentials, owner hostmask, services (NickServ/SASL), queue rate, DCC settings, SOCKS5 proxy, and logging level.

config/bot.json

{
  "irc": {
    "host": "irc.rizon.net",
    "port": 6697,
    "tls": true,
    "nick": "HexBot",
    "channels": ["#hexbot"]
  },
  "owner": { "handle": "admin", "hostmask": "*!ident@your.host" },
  "services": { "type": "anope", "sasl": true, "sasl_mechanism": "PLAIN" },
  "dcc": { "enabled": false, "port_range": [49152, 49171] },
  "proxy": { "enabled": false, "host": "127.0.0.1", "port": 9050 }
}

config/plugins.json

Plugins are auto-discovered from plugins/ — this file is only needed to override config, restrict channels, or disable specific plugins.

config/plugins.json

{
  "chanmod": {
    "channels": ["#hexbot"],
    "config": { "auto_op": true, "enforce_modes": false }
  },
  "greeter": {
    "channels": ["#hexbot"],
    "config": { "message": "Welcome to {channel}, {nick}!" }
  },
  "flood": { "enabled": false }
}

REPL Commands

Run with pnpm dev to get an interactive REPL with owner-level access — no IRC auth required.

repl

.help [cmd]	List commands or show detail for one
.status	Connection info, uptime, bind and user counts
.say <target> <msg>	Send a message to a channel or user
.msg <target> <msg>	Send a PRIVMSG to any target
.join / .part	Join or part a channel
.flags [handle] [+flags [#chan]]	View or set user flags
.adduser / .deluser / .users	User management
.chanset / .chaninfo	Per-channel plugin settings
.binds [plugin]	List active event binds
.plugins / .load / .unload / .reload	Plugin management

Hot-Reloading Plugins

Edit a plugin file, then reload it without restarting the bot:

reload

# In IRC (requires +o or higher):
!reload chanmod

# In the REPL:
.reload chanmod