HexBot

Requirements

• Node.js 24+ (manual install)
• pnpm (manual install)
• Docker + Compose (Docker install)

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.

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

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.

{
  "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 }
}

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

REPL Commands

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

Hot-Reloading Plugins

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

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

# In the REPL:
.reload chanmod