MeBox is a self-hosted private media management system for NAS, mini PCs, family sharing, and multi-device playback. This repository is a maintained fork of MediaStationGo, extended with stronger cloud playback, task queues, remote mounts, and permission controls.

In practice, MeBox gives you:

A modern web media library
An Emby/Jellyfin-compatible protocol gateway for third-party players
A single panel for local disks, download folders, and cloud storage

Key capabilities

Area	Highlights
Libraries	Movies, TV, anime, variety, music, custom libraries; multi-root scanning; poster wall; continue watching
Metadata	TMDb, Bangumi, Douban, TheTVDB, Fanart, NFO import, manual matching, scrape queue
Playback	Web player, HLS transcoding, danmaku, subtitles, play profiles, history and favourites
Emby protocol	Add MeBox in Infuse, SenPlayer, Fileball, etc. and sign in with MeBox accounts
Remote Emby mounts	Browse remote Emby libraries inside MeBox without a separate Emby client
Cloud & STRM	OpenList, CloudDrive2, 115, WebDAV; STRM sync; upload/download queues; direct or 302 playback
Downloads & organize	qBittorrent, site search/subscriptions, post-download organization, file manager
Users & permissions	Admin/regular users, expiry, NSFW toggle, play-profile PIN, granular permissions
Operations	Unified task queue, storage stats, DLNA casting, settings and logs

Tech stack

Backend: Go, Gin, GORM, SQLite or PostgreSQL, optional Redis and OpenSearch
Frontend: React 18, Vite, TypeScript, Tailwind CSS, Zustand
Deployment: Standalone Docker Compose templates, amd64/arm64 images, single-binary releases

Quick Start

Docker Compose is the recommended path. The repo ships four standalone templates; no .env is required.

mkdir -p MeBox && cd MeBox

# Simplest: one container with built-in SQLite
curl -fsSL https://raw.githubusercontent.com/truewhile/MeBox/main/docker-compose.simple.yml -o docker-compose.yml

# Or PostgreSQL tier for multi-user setups
# curl -fsSL https://raw.githubusercontent.com/truewhile/MeBox/main/docker-compose.yml -o docker-compose.yml

docker compose up -d

Open:

http://SERVER_IP:18080

Default login: admin / admin123 — change the password immediately.

Image:

ghcr.io/truewhile/mebox:latest

Deployment tiers

Pick one compose file. Do not stack multiple -f files.

Tier	File	Stack	Best for
Single image	`docker-compose.simple.yml`	MeBox + SQLite	Beginners, single-user, low-resource NAS
Tier 1	`docker-compose.yml`	MeBox + PostgreSQL	Most home NAS deployments
Tier 2	`docker-compose.standard.yml`	+ Redis	Multi-user, frequent Emby client refreshes
Tier 3	`docker-compose.search.yml`	+ OpenSearch	Very large libraries, advanced full-text search

Single-image notes

Only one MeBox container; database lives in ./data/mebox.db
Do not set MEBOX_DATABASE_DSN or it switches to PostgreSQL
Back up ./data; ./cache can be rebuilt

PostgreSQL notes

Primary DB: ./postgres; secrets and runtime files: ./data
Existing ./data/mebox.db migrates automatically on first start
After migration, point MEBOX_DATABASE_DB_PATH at a non-existent file to disable re-checks

Backup

Path	Notes
`./data`	JWT secret, config, SQLite DB or migration source
`./postgres`	PostgreSQL primary DB
`./cache`, `./redis`, `./opensearch`	Rebuildable

Update

docker compose pull mebox
docker compose up -d --no-deps mebox

Path mapping

The most common Docker mistake is mixing host paths with container paths.

Left side of volumes = real host/NAS path
Right side = container path; use /media/... in the web UI
Keep MEBOX_MEDIA_DIR / MEBOX_DOWNLOAD_DIR aligned with mounts when organizing or ingesting downloads

Example:

volumes:
  - /vol1/1000/Media:/media
  - /vol1/1000/Downloads:/downloads
environment:
  MEBOX_MEDIA_DIR: /vol1/1000/Media
  MEBOX_MEDIA_CONTAINER_DIR: /media
  MEBOX_DOWNLOAD_DIR: /vol1/1000/Downloads
  MEBOX_DOWNLOAD_CONTAINER_DIR: /downloads

First-time setup

Create a library with a container path such as /media/Movies, then scan
Add metadata providers (TMDb, Bangumi, etc.) in system settings
Optionally connect qBittorrent (http://host.docker.internal:8085 when qB runs on the host)
Optionally configure cloud accounts under STRM management
Add the server in Emby-compatible players at http://SERVER_IP:18080 using MeBox credentials

FAQ

Library scan is slow
Check path mapping and DB tier. Cloud scans also depend on API limits and folder size.

qBittorrent downloads are not organized
Ensure the download directory is mounted into the container and env vars match.

Hardlink fails with cross-device link
Hardlinks require the same filesystem/subvolume; use copy or symlink across disks or cloud mounts.

External player cannot connect
Use http://IP:18080 and a MeBox user account; reverse proxies need correct external URL and HTTPS headers.

Development

The backend embeds web/dist via go:embed. Build the frontend first.

npm --prefix web ci
npm --prefix web run build

go test ./...
go run ./cmd/server
npm --prefix web run dev

Release builds ship single-file binaries for Windows, Linux, and macOS on amd64 and arm64.

Acknowledgements

MeBox is forked from and continues to evolve MediaStationGo. Thank you to the upstream project for the media-library architecture, Emby-protocol compatibility, and self-hosted foundation.

Many cloud sync, STRM, and media-organization ideas in this project were also informed by qmediasync. Thank you for the reference implementation and design patterns.

Contributing

See CONTRIBUTING.md and SECURITY.md before opening issues or pull requests.

Star History

License

This project is licensed under GPL-3.0.