aly.codes
Retro Bulletin Board Systems on atproto. Web app and TUI.
atbbs.xyz
python
tui
atproto
bbs
1<div align="center">
2 <p>
3 <a href="https://github.com/alyraffauf/atbbs/actions/workflows/docker.yml"><img src="https://github.com/alyraffauf/atbbs/actions/workflows/docker.yml/badge.svg?branch=master" alt="Build"></a>
4 <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL%20v3-blue.svg" alt="License: AGPL v3"></a>
5 <a href="https://ko-fi.com/alyraffauf"><img src="https://img.shields.io/badge/Donate-Ko--fi-ff5e5b?logo=ko-fi&logoColor=white" alt="Ko-fi"></a>
6 </p>
7 <img width="128" height="128" src="assets/logo.svg" alt="@bbs logo">
8 <h1>@bbs</h1>
9 <p>Bulletin boards on <a href="https://atproto.com">atproto</a>. Web app and terminal client.</p>
10 <img src="assets/screenshot.png" alt="@bbs screenshot" width="800">
11</div>
12
13## Features
14
15- **Web and terminal**: Use it in your browser or dial in from a TUI.
16- **Serverless**: Run a BBS straight from your atproto account. No hosting required.
17- **Replies and quotes**: Flat threads with inline quoting.
18- **Attachments**: Upload files to threads and replies.
19- **Messages**: Know when someone replies to your thread or quotes you.
20- **Moderation**: Ban users, hide posts, manage your boards.
21- **Discovery**: Browse BBSes from across the network.
22
23## Install
24
25Requires Python 3.14+.
26
27### uv
28
29```bash
30uv tool install atbbs
31```
32
33### Homebrew
34
35```bash
36brew install alyraffauf/tap/atbbs
37```
38
39## Usage
40
41```bash
42atbbs # launch TUI
43atbbs dial aly.codes # dial a BBS directly
44atbbs serve # start the web server
45atbbs --help # see all options
46```
47
48## Web app
49
50### Docker
51
52```bash
53docker run -d -p 8000:8000 -v atbbs-data:/data -e PUBLIC_URL=https://your-domain.com ghcr.io/alyraffauf/atbbs:latest
54```
55
56Or with Docker Compose:
57
58```bash
59git clone https://github.com/alyraffauf/atbbs.git
60cd atbbs
61docker compose up -d
62```
63
64Visit `http://localhost:8000`.
65
66### From source
67
68Requires [Node.js](https://nodejs.org/) and [just](https://just.systems/).
69
70```bash
71git clone https://github.com/alyraffauf/atbbs.git
72cd atbbs
73npm install
74uv sync
75just dev # run dev server with hot reload
76just fmt # format code
77just build # build docker image
78```
79
80## Architecture
81
82atbbs has no backend database for content. All BBS data lives in atproto repos:
83
84- **Sysop records**: `xyz.atboards.site`, `xyz.atboards.board`, `xyz.atboards.news`
85- **Moderation records**: `xyz.atboards.ban`, `xyz.atboards.hide`
86- **User records**: `xyz.atboards.thread`, `xyz.atboards.reply`
87
88The web app and TUI query existing network infrastructure:
89
90- [Slingshot](https://slingshot.microcosm.blue/) — cached record and identity fetching
91- [Constellation](https://constellation.microcosm.blue/) — backlink index for discovering threads and replies
92- [UFOs](https://ufos.microcosm.blue/) — BBS discovery feed
93
94## Configuration
95
96On first run, atbbs generates:
97
98- `secrets.json` — app secret key and OAuth client signing key
99- `atbbs.db` — SQLite database for OAuth sessions
100
101**Web app (Docker)**: Set `ATBBS_DATA_DIR` to control where these are stored (default: `/data`). Set `PUBLIC_URL` to your domain for OAuth callbacks.
102
103**Web app (CLI)**: Use `atbbs serve --data-dir` and `--public-url` to configure. Defaults to the platform data directory and `http://{host}:{port}`.
104
105**TUI**: Data is stored in `~/.local/share/atbbs/` (Linux), `~/Library/Application Support/atbbs/` (macOS), or `%APPDATA%/atbbs/` (Windows).
106
107## License
108
109[AGPL-3.0](LICENSE.md)