2b893969d2
Replace python:3.12-slim (Debian) with python:3.12-alpine to reduce image size and eliminate 68 Debian-inherited CVEs. Upgrade pip to resolve CVE-2025-8869. Build deps installed temporarily for native extensions (cryptography) and removed after pip install. 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