Run a Beacon
Install the operator CLI, deploy the private stack, and claim administration.
A beacon is one self-hosted Minecraft server plus a private operator dashboard.
The Beacon CLI handles everything on the host — it generates the Docker
Compose files, secrets, and ingress configuration, then deploys and supervises
the stack. You don't write Compose files or run docker by hand.
A beacon can run indefinitely without ever appearing in a public directory. Listing on the Atlas is a separate, explicit step.
Alpha software
Deploy on a host you control and keep backups. Review the release notes before upgrading a live world.
Prerequisites
- Docker on the host: Docker Engine on Linux, or Docker Desktop on macOS / Windows for local private beacons. A small Linux VPS is ideal for an always-on server (Hosting on a VPS covers provisioning one from scratch).
- Node.js 20+ on the host (just to run the
beaconCLI). - One inbound TCP port for players — the first beacon uses
25565.
No GitHub token and no npm install: Beacon's images are public on GHCR.
Install the CLI
The installer pulls the public CLI image and links beacon onto your user
PATH. No token, no npm install.
Pick the host you are installing on. The page selects a likely OS automatically; the commands below update when you choose another one.
curl -fsSL https://beacon-mc.io/install.sh | shbeacon --versionDeploy and claim your beacon
Run guided setup
beaconThe onboarding wizard probes Docker, then walks you through Preflight → Mode
→ Details → Review → Deploy → Done. It writes the deployment directory
(~/.beacon by default), generates secrets, pins the release, streams the
image pull and start, and waits until the stack is healthy.
The Mode step is where you choose how the dashboard is reached: Tailscale (the default — private, no open ports) or a custom domain with automatic TLS.
Claim the admin account
When the stack is healthy, the Done screen prints a one-time
/claim?token=… URL. Open it to create the first administrator account, then
reopen the dashboard any time with beacon admin.
Missed the link before claiming? See I missed the admin claim URL.
Invite players and start playing
From the dashboard you manage everything about the running server — members,
invites, the allowlist, world settings, mods, backups, and the live map. See
Managing your beacon. Players connect to your host's
Minecraft address on port 25565.
Scripted setup
For automation or reproducible production deploys, skip the wizard with
beacon create --yes and explicit flags:
beacon create --yes \
--app-url https://mc.<tailnet>.ts.net \
--tailscale-auth-key tskey-... \
--mc-image itzg/minecraft-server:java25 \
--mc-version 26.1.2
beacon doctor
beacon up
beacon statusMinecraft image and version are required explicit inputs. See the CLI reference for every command and flag.
What comes next
Networking & access
Open the right ports and reach the dashboard over Tailscale or a domain.
Backups & restore
Snapshot your world on a schedule and copy backups offsite.
Updating Beacon
Upgrade and roll back safely from the dashboard or the CLI.
Publish a listing
Opt in only after the server identity and public address are ready.