aly.codes
Features#
- Web and terminal: Use it in your browser or dial in from a TUI.
- Serverless: Run a BBS straight from your atproto account. No hosting required.
- Replies and quotes: Flat threads with inline quoting.
- Attachments: Upload files to threads and replies.
- Messages: Know when someone replies to your thread or quotes you.
- Moderation: Ban users, hide posts, manage your boards.
- Discovery: Browse BBSes from across the network.
Install#
Requires Python 3.14+.
uv#
uv tool install atbbs
Homebrew#
brew install alyraffauf/tap/atbbs
Usage#
atbbs # launch TUI
atbbs dial aly.codes # dial a BBS directly
atbbs serve # start the web server
atbbs --help # see all options
Web app#
Docker#
docker run -d -p 8000:8000 -v atbbs-data:/data -e PUBLIC_URL=https://your-domain.com ghcr.io/alyraffauf/atbbs:latest
Or with Docker Compose:
git clone https://github.com/alyraffauf/atbbs.git
cd atbbs
docker compose up -d
Visit http://localhost:8000.
From source#
git clone https://github.com/alyraffauf/atbbs.git
cd atbbs
npm install
uv sync
just dev # run dev server with hot reload
just fmt # format code
just build # build docker image
Architecture#
atbbs has no backend database for content. All BBS data lives in atproto repos:
- Sysop records:
xyz.atboards.site,xyz.atboards.board,xyz.atboards.news - Moderation records:
xyz.atboards.ban,xyz.atboards.hide - User records:
xyz.atboards.thread,xyz.atboards.reply
The web app and TUI query existing network infrastructure:
- Slingshot — cached record and identity fetching
- Constellation — backlink index for discovering threads and replies
- UFOs — BBS discovery feed
Configuration#
On first run, atbbs generates:
secrets.json— app secret key and OAuth client signing keyatbbs.db— SQLite database for OAuth sessions
Web app (Docker): Set ATBBS_DATA_DIR to control where these are stored (default: /data). Set PUBLIC_URL to your domain for OAuth callbacks.
Web app (CLI): Use atbbs serve --data-dir and --public-url to configure. Defaults to the platform data directory and http://{host}:{port}.
TUI: Data is stored in ~/.local/share/atbbs/ (Linux), ~/Library/Application Support/atbbs/ (macOS), or %APPDATA%/atbbs/ (Windows).