A tiny local-first sharing hub for files, chat, posts, media, and search.
FastBox is a modern, hackable take on the classic PirateBox idea: a self-contained local web app for anonymous file sharing, real-time chat, threaded discussions, media browsing, and full-text search.
It runs as a single FastAPI application file with SQLite and filesystem storage.
No accounts.
No cloud dependency.
No frontend build step.
No complicated deployment.
FastBox gives a local network a lightweight shared space for:
- anonymous file uploads and downloads
- real-time WebSocket chat
- persistent threaded message board posts
- browser-native media previews
- unified full-text search
- simple moderation cleanup tools
- storage statistics
It is designed for classrooms, workshops, hackathons, LANs, events, makerspaces, homelabs, and offline-first experiments.
Most collaboration tools assume accounts, cloud connectivity, teams, permissions, and hosted infrastructure.
FastBox assumes something simpler:
A small group of people on the same network need to share things quickly.
FastBox is intentionally compact. The main application lives in fastbox.py, backed by SQLite and local storage, so it is easy to run, inspect, fork, and modify.
- anonymous uploads
- persistent downloads
- UUID stored filenames
- original filename preservation
- upload size limits
- path traversal protection
- mobile-friendly drag-and-drop upload area
- double-click / double-tap file picker
- global WebSocket room
- anonymous nicknames
- persisted chat history
- join and leave events
- malformed payload handling
- simple rate-limit hook
- create threads
- reply to threads
- Markdown support
- HTML sanitization
- image attachments
- timestamps
- reply counts
- classic uploaded-file list
- gallery view for image previews
- video playback
- audio playback
- PDF embedding
- unsupported media fallback
- media type filtering
- SQLite FTS5
- unified
/search?q=...route - searches uploads, chat, threads, and replies
- result filtering
- highlighted matches
- safe query normalization
- single moderation password
- delete uploads
- delete board threads
- delete chat messages
- delete message board attachments
- storage statistics page
- configuration page
- graceful error pages
- logging
- 100% app test coverage
git clone https://github.com/your-org/fastbox.git
cd fastbox
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txtOn Windows:
python -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txtpython fastbox.pyOpen:
http://127.0.0.1:8000
For LAN access, open the server machine's local IP address from another device:
http://192.168.x.x:8000
|
|
|
|
|
|
|
|
FastBox uses environment variables for its small configuration surface.
| Variable | Default | Description |
|---|---|---|
HOST |
0.0.0.0 |
Uvicorn bind host |
PORT |
8000 |
Uvicorn port |
FASTBOX_ADMIN_PASSWORD |
fastbox |
Moderation password for delete tools |
FASTBOX_LOG_LEVEL |
INFO |
Logging level |
Recommended:
export FASTBOX_ADMIN_PASSWORD='use-a-long-random-password'
python fastbox.pyFastBox is intentionally boring.
Browser
|
| HTTP + WebSocket
v
FastAPI app
|
|-- SQLite
| |-- upload metadata
| |-- chat history
| |-- board threads
| |-- replies
| |-- FTS5 search index
|
|-- filesystem
|-- storage/uploads/
|-- storage/attachments/
The app uses:
- FastAPI for HTTP and WebSocket routes
- SQLite for metadata and full-text search
- Filesystem storage for uploaded files and board attachments
- Browser-native media rendering for previews and playback
- Inline HTML helpers to preserve the single-file architecture
fastbox/
├── fastbox.py
├── requirements.txt
├── pytest.ini
├── .coveragerc
├── README.md
├── QUICKSTART.md
├── USER_GUIDE.md
├── COVERAGE_REPORT.txt
├── static/
│ ├── favicon.ico
│ └── screenshots/
├── storage/
│ ├── uploads/
│ └── attachments/
└── tests/
Runtime files are created automatically.
Open the homepage, then:
- drag a file onto the upload region, or
- double-click / double-tap the upload region and choose a file
The file uploads automatically and the recent uploads list refreshes without navigating away.
Visit:
/chat
Choose a nickname and send messages in the global room.
Visit:
/board
Create a thread with a nickname, title, Markdown body, and optional image attachment.
Visit:
/files
Use the view toggle to switch between List and Gallery.
Visit:
/search?q=meeting
FastBox is built for trusted local networks.
Implemented protections include:
- filename sanitization
- UUID stored filenames
- path traversal checks
- upload size limits
- image-only board attachments
- Markdown escaping and HTML sanitization
- safe FTS5 query normalization
- graceful error pages
- moderation delete actions behind a single password
FastBox does not provide:
- per-user accounts
- roles or permissions
- public internet hardening
- built-in HTTPS
- advanced moderation workflows
Run the full suite:
python -m pytestGenerate terminal coverage:
python -m pytest --cov=fastbox --cov-report=term-missingGenerate HTML coverage:
python -m pytest --cov=fastbox --cov-report=htmlNo. Once dependencies are installed, it can run entirely on a local network.
No. Normal use is anonymous by design.
Yes. Moderation delete tools are protected by a single password.
No. Media rendering is browser-native.
Possible future improvements:
- optional per-room namespaces
- richer moderation tools
- RSS feeds
- import/export tools
- optional authentication mode
- Docker image
- QR-code LAN join page
- plugin hooks
FastBox is licensed under the Apache License 2.0.
See LICENSE.