CataclysmBBS

CataclysmBBS is an old-school, SSH-first bulletin board for Raspberry Pi and other Linux systems. Every member authenticates as a real operating-system user, runs bb, and gets a responsive neon-green terminal interface.

Status: version 1.6.1 is deployed and tested on Raspberry Pi OS based on Debian 13 (ARM64), with Python 3.13.

What it looks like

These screens show the real responsive TUI, neon theme, selection states, and letter-driven navigation with a full-throttle wasteland board in action. Click either image for the full-size version.

Overview and recent signals

Forum conversation

It includes:

• five seeded forums, topics, threaded replies, search, and unread counts;
• inbox/sent mail with replies, per-user deletion, and unread counts;
• a member directory with roles and posting activity;
• private, BBS-native IRC-style chat with channels, a nick list, commands, per-user settings, and seen-only history;
• a live Overview IRC-participant counter and BBS-wide server-pushed screen updates, with small resource-scoped events instead of polling;
• image, video, and general-file attachments up to an administrator-set limit;
• terminal-assisted local uploads, SFTP-staged full server paths and wildcards, multi-file upload/download selection, and aggregate progress indicators;
• optional inline image viewing for Kitty, iTerm2, and Sixel terminals, with a safe text-only default;
• an Admin menu for complete forum/category, topic, post, banner, and OS-backed user administration;
• an administrator-set board identity rendered with proportional, kerned FIGlet terminal art and width-aware fallbacks, with permanent CataclysmBBS product branding in the main frame;
• a responsive curses interface that works from compact terminals upward;
• six per-user color schemes: neon green by default, plus amber phosphor, electric cyan, synthwave magenta, ice blue, and red alert;
• a privileged local service and Unix socket, keeping the SQLite database away from untrusted shell users;
• parameterized SQL, OS-peer authentication, path/name validation, SHA-256 checksums, rate limits, and conservative file permissions;
• a bb-admin tool for OS accounts, SSH keys, moderators, board statistics, backups, and service checks.

User experience

ssh alice@your-pi
bb

Inside the board:

• ↑/↓ or j/k selects an item.
• On Overview, the selection moves continuously through Channel Matrix and Latest Signals; Enter opens the highlighted forum or recent topic. Two visual spacer rows separate the sections, but arrow navigation skips them and always lands on real content.
• The persistent footer uses classic first-letter navigation: [O]verview [I]RC [M]ail [U]sers [X]fers [S]earch [T]heme [H]elp [Q]uit. Only administrators see [A]dmin; the running version stays visible at the far-right edge of the footer bar.
• n creates a topic, r replies, and f attaches a file.
• x opens the Transfer Center; Space selects multiple files and f selects attachment names using a wildcard.
• v views an image using the saved display mode; g opens Graphics settings from the Transfer Center.

When composing a forum topic or reply, press Esc, then choose [S]ave, [C]ontinue, or [D]iscard. Mail composition uses the same letter-driven menu but labels the action [S]end.

Press m for Mail. The inbox and sent list switch with Tab; n composes, r replies, and d deletes from either the list or an open message after confirmation. Deleting mail removes only your copy, so a recipient deleting an inbox item does not erase the sender's sent copy.

IRC-style chat

Press i to enter the private, built-in chat service. This is an IRC-style BBS client, not a gateway to public Internet IRC networks. The screen uses familiar #channel, <nick>, action-line, scrollback, and online-nick conventions.

Press c to type a chat line; Enter sends it and Esc returns to the letter menu. Press l to open the channel list, then select a channel and press Enter to switch. Slash commands are:

• /join #channel — join an existing channel or create a valid new one;
• /me action — send a classic IRC action line;
• /clear — clear the current session display;
• /settings, /help, and /quit.

The [S]ettings screen controls the number of history lines to auto-load (25–500, default 500), timestamps, the nick list, and audible @mention alerts. History is personal and seen-only: CataclysmBBS retains a rolling maximum of 500 lines that the user was present to see. It does not accumulate offline chat. Returning to IRC automatically loads that personal seen history. Long lines wrap at word boundaries with hanging indentation under the original timestamp and nickname.

To upload directly from the Mac running iTerm2, select one of your posts, press x, then u. The Mac file picker opens; press Cmd-Shift-G to paste an exact local path such as /Users/alice/Desktop/photo.jpg, or select multiple files. CataclysmBBS receives the selection and shows aggregate board-upload progress.

Kitty users can choose its confirmed terminal-transfer path. If the terminal does not support local transfer, stage files with SFTP:

sftp alice@your-pi
sftp> put photo.jpg bbs-files/uploads/photo.jpg

Then open one of your posts, press x, and press e. Enter a full Pi path such as /home/alice/bbs-files/uploads/photo.jpg or a wildcard such as /home/alice/bbs-files/uploads/*.jpg. Choose one or more matches and watch the aggregate upload progress. Downloads use the same multi-select workflow and require a full destination directory under the logged-in user's home.

SSH itself has no universal image channel. CataclysmBBS therefore defaults to text-only metadata and lets each user explicitly select Kitty, iTerm2, or Sixel display. Press v to preview a selected image. Kitty preview accepts PNG; iTerm2 accepts the image formats supported by macOS; Sixel preview requires /usr/bin/img2sixel on the Pi. Unsupported formats and files over 8 MiB retain the normal download path without sending graphics escape sequences.

Only administrators see [A]dmin. Press a to add, edit, reorder, or delete top-level forum categories, including their Overview descriptions; add, rename, move, or delete topics; add, edit, move, or delete posts; change the board's large banner name with [I]dentity; or manage users. [B]ack consistently returns to the previous screen. Forum [E]dit opens one dialog with Name and Overview Description visible together. Use Tab or the arrow keys to switch fields, then Esc for [S]ave, [C]ontinue, or [B]ack. Opening posts cannot be moved or deleted separately—move or delete their topic instead. Category and content deletion requires typed confirmation, and the final forum cannot be deleted.

Connected TUI sessions receive a compact authenticated update stream. Forum, topic, post, mail, file, user, banner, and IRC-presence changes identify only the affected resources; each client reloads its visible affected screen and coalesces bursts into one redraw. Idle clients issue no periodic screen or counter requests, which keeps slow SSH links responsive. An OS pipe wakes the blocked curses input loop as soon as an event arrives, so the updated screen is painted immediately without waiting for a keypress.

New-user creation includes a multiline SSH-public-key paste box. BBS deletion blocks future board access, deletes private messages involving the account, and preserves public content under Deleted User. Optional OS-account deletion preserves that user's home directory.

Install

On the target Pi:

sudo ./install.sh --admin-user "$USER"

The installer adds the current admin to the neonbbs access group, installs a dedicated neonbbs-svc service account, initializes the database, and starts neonbbs.service. Log out and back in once so the new group is applied.

Create a member with an SSH public key:

sudo bb-admin user-add alice --key /path/to/alice.pub

Or create the account and set a password interactively:

sudo bb-admin user-add alice
sudo passwd alice

Key authentication is strongly recommended. To make the account BBS-only, add --restricted; interactive SSH launches CataclysmBBS directly while the OpenSSH SFTP subsystem remains available:

sudo bb-admin user-add alice --key /path/to/alice.pub --restricted

Other operations:

sudo bb-admin stats
sudo bb-admin user-list
sudo bb-admin role alice moderator
sudo bb-admin backup /var/backups/neonbbs
sudo bb-admin health

The installer grants only the enrolled administrator passwordless access to the two OS-account actions used by the TUI (user-add and os-user-delete). Board data administration stays on the peer-authenticated service API.

Diagnostics and audit logs

Every service request is logged to the system journal with a short request ID, OS username, operation, relevant object IDs, outcome, error, and elapsed time. This captures the use case that triggered a problem without recording post bodies, mail text, file data, or cryptographic keys.

sudo journalctl -u cataclysmbbs.service --since today
sudo journalctl -u cataclysmbbs.service -f
sudo journalctl -u cataclysmbbs.service | grep '"user":"alice"'
sudo bb-admin health

Large file-transfer chunks and server-sent event-stream keepalives do not create normal request-log noise. Event subscription, transfer begin/finish, and IRC enter, list, manual refresh, join, send, settings, and leave actions remain attributable to the OS user. Chat bodies are not logged. Unexpected exceptions include a server-side traceback in the journal.

Files and services

Path	Purpose
/opt/cataclysmbbs	root-owned application code
/usr/local/bin/bb	TUI launcher
/usr/local/sbin/bb-admin	administrator tool
/var/lib/neonbbs	private database and attachments
/run/neonbbs/neonbbs.sock	authenticated local API socket
~/bbs-files/uploads	a member's SFTP upload inbox
~/bbs-files/downloads	a member's exported downloads

Development

PYTHONPATH=src python3 -m unittest discover -s tests -v

The project intentionally uses only Python's standard library at runtime.

Documentation

• Architecture and threat model
• Installation, operation, backup, and recovery
• Security policy
• Contribution guide
• Release history
• Third-party font notices

CataclysmBBS is publicly viewable source code, but it is not open source: copyright remains with sundruid and all rights are reserved. See LICENSE.