bouncer

IRC bouncer with SOCKS5 proxy support and persistent message backlog.

Features

• Multi-network multiplexing: single client connection sees all networks via /network suffixes
• 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)

1. Bouncer connects to IRC server via SOCKS5 with a random identity
2. Survives 15s probation (K-line detection)
3. Switches to your configured nick
4. Joins configured channels
5. 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