Stream your own movies & TV to your devices — at home or away — with no cloud lock-in, no paywall, no bloat.
A lean, self-hosted media server. A deliberately minimal Plex alternative that nails the one thing that matters: reliably watching your own movies and TV on your devices, anywhere.
License: AGPLv3 · Scope: v1 (movies + TV only) · Status: scaffold / in development
lotusfield is built against three founding grievances. Each maps to a design principle that the project must respect:
| Grievance | Principle |
|---|---|
| Bloat — heavy, feature-creeping software | Lean scope (movies + TV only), small dependency surface, no unrequested abstraction |
| Remote-access friction — relays, port-forwarding, cert hassles | Remote access is a first-class concern; recommended path is a VPN mesh with no open ports |
| Paywall creep — basics moving behind a paid tier | Nothing is ever paywalled. AGPLv3 keeps lotusfield and any networked derivative free and open |
In: movie & TV library scanning by naming convention; TMDB metadata + locally cached artwork (optional, degrades gracefully); browse/search/detail; direct play + on-the-fly adaptive-HLS transcoding (software + Intel QuickSync/VAAPI); per-user watch state & resume; sidecar subtitles; multi-user within one household; forced admin password on first run; PWA install; documented OpenAPI contract.
Out (v1): music & photos; offline download; native mobile/desktop apps; serving external/non-household users; subtitle burn-in & ASS/SSA styling; non-Intel hardware encoders (NVENC, Pi); live TV / DVR; deep metadata (cast, trailers, collections); fuzzy/AI matching; public-by-default exposure or any built-in cloud relay.
See docs/prd-v1.md for the authoritative spec and ROADMAP.md
for the milestone order.
lotusfield is a Python backend (FastAPI) plus a React + TypeScript PWA frontend. Run both for local development.
cd backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
uvicorn app.main:app --reloadBackend serves on http://localhost:8000. Check it: curl http://localhost:8000/api/health
→ {"status": "ok", "service": "lotusfield"}.
cd frontend
npm install
npm run devFrontend dev server runs on http://localhost:5173 and proxies /api to the backend on
port 8000.
Copy .env.example to .env and fill in values before running with real media. See
CONTRIBUTING.md for the full dev setup, testing discipline, and tooling.
lotusfield ships as a single small Docker image (a python:slim base with ffmpeg bundled). One
container serves both the API and the built PWA on port 8000 — same origin, no CORS.
cp .env.example .env
# Generate the REQUIRED signing key (a known placeholder is rejected at startup):
python -c "import secrets; print(secrets.token_hex(32))" # → put in LOTUSFIELD_SECRET_KEY
# Point the media bind-mount in docker-compose.yml at your library (mounted READ-ONLY), then:
docker compose up -d --buildOn first load you are forced to create the admin account and password — there are no default credentials. Then point at your media, optionally add a free TMDB key, and trigger a library scan.
HTTPS is required for login to persist (the session cookie is
Secure). Use Tailscale Serve or a reverse proxy to terminate TLS — see the remote-access profiles below.
Full walkthrough (including the manual docker build / curl /api/health smoke check):
docs/deployment.md.
lotusfield is transport-agnostic: it serves HTTP and has no knowledge of how a client reached it. Two deployment profiles are documented:
- Tailscale / WireGuard mesh (recommended/default) — most secure, no open ports, no
certificates, no third-party relay. See
docs/deployment-tailscale.md. - Reverse proxy + Let's Encrypt (advanced / public) — for exposing publicly, with
hardening guidance. See
docs/deployment-reverse-proxy.md.
lotusfield sends zero telemetry and phones home to no one. Your library and usage stay entirely under your control.
AGPLv3. Because lotusfield is network server software, the AGPL guarantees that it and any networked derivative stay free and open — directly defending against paywall creep.