FileCodeBox
A self-hosted file locker that works out of the box
Share files and text anonymously. No account required—just enter a passcode.
docker run -d --restart unless-stopped -p 12345:12345 -v ./data:/app/data --name filecodebox lanol/filecodebox:2.5.0 # x-release-please-version
http://localhost:12345, complete first-run setup, and start sharing.
Why FileCodeBox
Effortless sharingNo account system. Upload content, get a passcode, and let the recipient download the file or read the text. |
Self-hosting firstRun everything in one Docker container. Your data and configuration stay on infrastructure you control. |
Built for real workloadsBatch, chunked, and presigned uploads with expiration policies, capacity limits, an admin console, and multiple storage backends. |
Highlights
| Sharing | Administration & security | Storage & delivery |
|---|---|---|
| Unified file and text sharing | Secure first-run setup | Local filesystem |
| Drag, paste, and batch upload | Admin sessions and access control | S3-compatible storage |
| Random or custom passcodes | Upload and passcode rate limits | OneDrive and WebDAV |
| Time, count, or permanent expiry | Automatic cleanup and quotas | OpenDAL integrations |
| Chunked upload and resume | File and storage health views | Multi-architecture Docker images |
| Responsive UI and dark mode | Chinese and English admin UI | Reverse-proxy friendly |
Product Preview
![]() |
![]() |
| A focused flow for sending files and text | A dashboard built around file health and storage policy |
The active theme lives in FileCodeBoxFronted. Image builds automatically use the latest commit from its default branch.
Quick Start
Docker Compose
services:
filecodebox:
image: lanol/filecodebox:2.5.0 # x-release-please-version
container_name: filecodebox
restart: unless-stopped
ports:
- "12345:12345"
volumes:
- ./data:/app/data
docker compose up -d
Pin a version in production for reliable rollbacks. latest tracks the newest stable release; edge-* identifies development images from master.
Run from source
git clone https://github.com/vastsa/FileCodeBox.git
cd FileCodeBox
pip install -r requirements.txt
python main.py
The default URL is http://localhost:12345. Follow the first-run flow to create the administrator password.
Reverse proxy
Nginx example
location / {
proxy_pass http://127.0.0.1:12345;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 100m;
}
How It Works
| Action | Flow |
|---|---|
| Share files | Select or drop files → choose expiry → receive a passcode |
| Share text | Enter text → choose expiry → receive a passcode |
| Retrieve content | Enter a passcode → read text or download files |
| Manage the service | Open /#/admin → inspect files, metrics, and settings |
Uploads also work from the command line:
curl -X POST "http://localhost:12345/share/file/" \
-F "file=@/path/to/file.txt" \
-F "expire_value=1" \
-F "expire_style=day"
For complete API, chunk upload, and storage configuration details, see:
Architecture
Browser / CLI
│
▼
FastAPI · Uvicorn
│
├── SQLite · Tortoise ORM
├── Local / S3 / OneDrive / WebDAV / OpenDAL
└── Vue 3 · Vite frontend
| Layer | Technology |
|---|---|
| API | FastAPI · Pydantic · Uvicorn |
| Data | SQLite · Tortoise ORM |
| Async I/O | aiofiles · aiohttp · aioboto3 |
| Frontend | Vue 3 · TypeScript · Vite · Tailwind CSS |
| Delivery | Docker · GitHub Actions · VitePress |
Development
# Backend
pip install -r requirements.txt
python main.py
# Tests
python -m pytest tests
The frontend is maintained in FileCodeBoxFronted:
pnpm install
pnpm dev
FAQ
How do I back up or migrate the service?
Stop the service and back up the entire data directory. It contains the database, runtime configuration, and locally stored files.
How do I change the upload size?
Update the upload limit in the admin console. If you use Nginx, a CDN, or another gateway, update its request body limit as well.
Which storage backends are supported?
Local, S3, OneDrive, WebDAV, and OpenDAL are built in. See the storage guide for configuration details.
Contributing
Issues, feature ideas, and pull requests are welcome. Use clear Conventional Commits when contributing code:
fix: resolve file download issue
feat: add a storage adapter
License
FileCodeBox is released under LGPL-3.0. Use it in accordance with applicable laws and retain the project URL and copyright notice.








