0d762ced49
PING watchdog sends PING after configurable silence interval and disconnects on timeout, detecting stale connections that TCP alone misses. IRCv3 server-time capability is requested on every connection; timestamps are injected on dispatch and backlog replay for clients that support message tags. Push notifications via ntfy or generic webhook fire on highlights and PMs when no clients are attached, with configurable cooldown and optional SOCKS5 routing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bouncer
IRC bouncer with SOCKS5 proxy support and persistent message backlog.
Features
- Multi-network multiplexing: single client connection sees all networks via
/networksuffixes - All outbound connections routed through SOCKS5 proxy
- Stealth connect: registers with a random pronounceable nick and generic identity
- Probation window: waits 15s after registration to detect K-lines before revealing real nick
- Persistent message backlog (SQLite) with replay on reconnect
- Multiple clients can attach simultaneously
- Password authentication
- TLS support for IRC server connections
- Automatic reconnection with exponential backoff
- Local DNS resolution with multi-address failover
Quick Start
cd ~/git/bouncer
make dev
cp config/bouncer.example.toml config/bouncer.toml
$EDITOR config/bouncer.toml
bouncer -c config/bouncer.toml -v
Connect
From your IRC client, connect to 127.0.0.1:6667 with:
PASS yourpassword
A single connection gives you all configured networks. Channels and nicks
appear with a /network suffix:
Client sees: Server sends/receives:
#libera/libera <-> #libera (on libera network)
#debian/oftc <-> #debian (on oftc network)
user123/libera <-> user123 (on libera network)
How It Works
IRC Client(s) --> [bouncer:6667] --> Router --> [SOCKS5:1080] --> IRC Server(s)
|
Backlog
(SQLite)
- Bouncer connects to IRC server via SOCKS5 with a random identity
- Survives 15s probation (K-line detection)
- Switches to your configured nick
- Joins configured channels
- Clients connect to bouncer, receive backlog replay and channel state
Podman Deployment
cp config/bouncer.example.toml config/bouncer.toml
$EDITOR config/bouncer.toml
make build
make up
make logs
See docs/DEPLOY.md for full container documentation.
Documentation
| Document | Description |
|---|---|
| docs/INSTALL.md | Prerequisites and setup |
| docs/USAGE.md | Comprehensive guide |
| docs/DEPLOY.md | Podman container deployment |
| docs/CHEATSHEET.md | Quick reference |
| docs/DEBUG.md | Troubleshooting |
Development
make dev # Install with dev deps
make test # Run tests
make lint # Run linter
make fmt # Format code