Cubeherd

A lean web dashboard for itzg/docker-minecraft-server: create, start, update, manage and uninstall Minecraft servers (including modpacks from Modrinth and CurseForge).

Cubeherd runs on the same host as the Minecraft servers and takes next to nothing from them: a single Go binary, around 10 MB of RAM and 0 % CPU when idle, no database. Live data only flows while a page is open.

Screenshots

Getting started

As a container (recommended)

sudo mkdir -p /srv/cubeherd
docker compose -f deploy/compose.yml up -d --build

Then open http://<host>:8420 and set the admin password on first visit.

The data directory must have the same path inside the container as on the host (/srv/cubeherd:/srv/cubeherd), because Docker resolves the Minecraft servers' bind mounts on the host.

As a binary

Requirement: Docker with the Compose plugin on the host.

CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o cubeherd ./cmd/cubeherd
sudo CUBEHERD_DATA=/srv/cubeherd ./cubeherd

Variable	Default	Meaning
CUBEHERD_DATA	/srv/cubeherd as root, otherwise ./cubeherd-data	Data directory
CUBEHERD_LISTEN	:8420	Web server address
DOCKER_HOST	/var/run/docker.sock, falling back to ~/.docker/run/docker.sock	Docker socket
TZ	UTC	Default time zone, as long as none is chosen in the settings

Security

Anyone who can operate Cubeherd controls Docker and therefore, in practice, the entire host. Only expose Cubeherd on your LAN or via VPN, never directly to the internet. It has a single admin account (bcrypt), signed session cookies (SameSite=Strict), login throttling and CSRF protection.

Features

• Create: Vanilla, Paper, Purpur, Folia, Fabric, Quilt, Forge, NeoForge, or a modpack from Modrinth or CurseForge. The Java image is derived from Mojang's version data (e.g. java25 for Minecraft 26.x).
• Operation: start, stop, restart, status including autopause and crash cause, live console with RCON, CPU/RAM, online players.
• Settings: world, RAM, Aikar flags, autopause, port, any additional itzg variables.
• Players: whitelist, operators, bans.
• Updates: Minecraft version, modpack version, itzg image.
• Uninstall: keep the data or delete everything.
• Adopt existing itzg containers.
• Backups: manual, scheduled, automatic before updates, restore, download. Optionally uploaded to S3-compatible storage (AWS S3, Backblaze B2, Hetzner, Wasabi, Cloudflare R2, MinIO), and optionally kept only there.
• Backup checks: every archive is read back after it is made, damaged ones are flagged, and a banner warns when backups fail or stay overdue.
• Performance: live TPS, tick time (MSPT), CPU and memory with a short history, per dimension on Forge and NeoForge. Queried over RCON only while the tab is open.
• Mods & plugins: search Modrinth, CurseForge and Spigot, add and remove entries (itzg installs them on startup), upload your own JARs. Also works on top of modpacks.
• Files & worlds: file browser with editor, upload, download and delete; export a world as a ZIP and import one.
• Idle & limits: pause or fully stop when nobody is playing; per-server CPU limit.
• Language & time zone: UI in German or English, time zone for schedules, dates and server logs.

Each server lives in the data directory as servers/<id>/compose.yml and can also be run with docker compose without Cubeherd. See ARCHITECTURE.md for details on the architecture.

Development

go run ./cmd/cubeherd          # http://localhost:8420, data in ./cubeherd-data
go test ./...
FC_PROBE=<container> go test ./internal/docker -run Live -v   # against a running itzg container
FC_NET=1 go test ./internal/sources -run Live -v               # against Mojang/Modrinth

The clickable design prototype is in prototype/index.html.

License

Cubeherd is licensed under the MIT License. Bundled components (htmx, fonts, golang.org/x/crypto) and their licenses are listed in THIRD_PARTY_NOTICES.md. Cubeherd is not an official Minecraft product and is not affiliated with Mojang Studios or Microsoft.