---
tags:
  - service
  - josiedot
  - irc-now
domain: irc.bot
status: active
stack:
  - Rust
  - Axum
  - PostgreSQL
  - mlua
auth: Keycloak
---
# irc.now Bot Service

Managed IRC bot runtime. users create bots, write Lua scripts, and the service
keeps them connected to IRC networks via soju bouncers.

## URLs
- https://irc.bot

## Stack
- Rust (Axum 0.8, mlua 0.11, tokio-rustls)
- PostgreSQL (CNPG bot-db)
- OIDC auth via Keycloak
- Lua 5.4 sandbox per bot (8MB memory, 1M instruction limit)

## Architecture
- Axum web service (not a K8s operator)
- bots stored in PostgreSQL, IRC connections multiplexed in-process via tokio
- one mlua Lua 5.4 VM per bot
- WebSocket live log streaming via broadcast channels

## Database Tables
- `bots` -- bot instances (id, user_id, name, nick, network_addr, SASL creds, channels, status)
- `bot_scripts` -- Lua scripts per bot (name, source, enabled)
- `bot_logs` -- log entries (level, message, timestamp)
- `bot_kv` -- key-value store per bot

## Lua API
- `irc.send(channel, text)`, `irc.join(channel)`, `irc.part(channel)`, `irc.nick(new_nick)`
- `kv.get(key)`, `kv.set(key, value)`, `kv.delete(key)`, `kv.list()`
- `log.info(msg)`, `log.warn(msg)`, `log.error(msg)`
- `http.get(url)` -- rate-limited (10 req/min per bot)
- `timer.after(secs, fn)`, `timer.every(secs, fn)`

## Event Handlers
- `on_message(nick, channel, text)`
- `on_join(nick, channel)`
- `on_part(nick, channel, reason)`
- `on_kick(nick, channel, target, reason)`
- `on_nick(old_nick, new_nick)`
- `on_notice(nick, target, text)`

## Template Scripts
- linkbot -- URL title fetcher
- rsswatch -- RSS feed checker with KV persistence
- sed -- s/typo/fix/ corrections
- watchdog -- channel moderation (!warn, !kick)

## Plan Limits
- Free: 1 bot
- Pro: 5 bots
- Team: unlimited

## Deployment
- OCP namespace: irc-josie-cloud
- Build: `oc start-build bot --from-archive` (tar of workspace)
- Containerfile: `crates/bot/Containerfile` (rust:1.88 -> ubi9-minimal, mlua vendored Lua)
- WebService CR: `deploy/instances/bot.yaml`
- TLS: cert-manager, letsencrypt-prod
- Resources: 128Mi/512Mi memory, 100m/1000m CPU

## Infra
- CNPG cluster `bot-db` in irc-josie-cloud (provisioned)
- Keycloak client `bot` with redirect `https://irc.bot/auth/callback`
- Secret `oidc-bot` with client credentials
- BuildConfig `bot` with dockerfilePath `crates/bot/Containerfile`
- PV: hostPath `/var/mnt/data/bot-db`, UID 1001260000

## Source
- Repo: ~/development/irc-now
- Crate: `crates/bot/`

## Business Metrics
Background task records Prometheus gauges every 60s:
- `irc_now_bots_total`, `irc_now_bots_enabled`, `irc_now_bots_running`

## Related
- [[irc-bot-landing]]
- [[irc-now-portal]]
- [[irc-now-soju-operator]]