Configuration
The .env keys the CLI manages, how to size memory, and where each setting actually lives.
Beacon splits configuration into two layers with clear ownership:
- Infrastructure — ports, ingress, secrets, the pinned version, the
Minecraft image. Set in
.envin the deployment directory, owned by the CLI. - Gameplay & operations — difficulty, game mode, world generation, the allowlist, MOTD, backup schedules. Managed in the dashboard, stored in the database.
Don't hand-edit compose files or server.properties
The CLI regenerates docker-compose.yml and friends on beacon upgrade /
beacon restart, and Beacon generates server.properties from the dashboard.
Hand edits to those files are not authoritative. Change infrastructure in
.env, and gameplay in the dashboard.
Key .env values
beacon create writes these for you; you'll mostly only revisit them to tune
memory or change the Minecraft version. After editing .env, apply changes
with beacon restart.
| Key | Purpose |
|---|---|
BEACON_VERSION | Pinned Beacon release (concrete version, never latest). |
MC_IMAGE | The itzg/minecraft-server image tag (e.g. :java25). |
MC_VERSION | The Minecraft release (e.g. 26.1.2). |
MC_MEMORY | JVM heap for the server (e.g. 4G). |
MC_CPU_LIMIT | Optional CPU quota in cores; 0 = unlimited (default). See Capping CPU. |
MC_HOST_PORT | Host TCP port published to players (default 25565). |
MC_VOICE_HOST_PORT | Host UDP port for voice chat (default 24454). |
MC_PUBLIC_HOST | Friendly address shown in the How to join panel. |
PUBLIC_APP_URL | The dashboard's public URL. |
COMPOSE_PROFILES | tailscale or custom-domain — selects the ingress. |
TS_AUTHKEY | Tailscale auth key (Tailscale mode). |
BEACON_DOMAIN / BEACON_ACME_EMAIL | Domain + ACME contact (custom-domain mode). |
MC_RCON_PASSWORD, ADMIN_RPC_TOKEN, BEACON_SESSION_SECRET | Generated secrets — leave them alone. |
Pin a concrete version
BEACON_VERSION must be an exact release — the moving latest tag is
rejected because it hides what's running and breaks update detection.
beacon doctor warns if an install drifts to latest or unset.
Sizing memory
MC_MEMORY is the JVM heap, not total host memory — and you don't add headroom
by hand. The CLI sizes the Minecraft container with off-heap headroom on top of
the heap, and beacon up warns if the beacons on a host over-commit its RAM.
Pick a VPS that fits the sizing table, then
set MC_MEMORY to the heap you want and apply:
# in .env
MC_MEMORY=6Gbeacon restartCapping CPU
MC_CPU_LIMIT bounds how many CPU cores the Minecraft container may use
(Docker's --cpus). It defaults to 0 — unlimited — so it does nothing until
you set it. It's an opt-in knob for two cases:
- Shared hosts — cap each beacon so one can't monopolise the box's CPU, the
same way
MC_MEMORY_LIMITcaps RAM. - Small hosts — reserve a core for the OS and the live-map renderer (which
runs in
admin-rpc, sharing the same cores) so a render pass can't stall the game.
# in .env
MC_CPU_LIMIT=3
beacon restartA positive cap is re-applied on every managed recreate, so it survives loadout and settings changes. It bounds total CPU, not per-tick speed — Minecraft's main loop is single-threaded, so this is about isolation between workloads, not making one server tick faster.
Minecraft version and loader
MC_IMAGE + MC_VERSION pin the server. The default loader is Paper; you
can switch the loader from the dashboard's server settings once running. Pin a
known-good MC_VERSION and check release notes before bumping — world upgrades
are effectively one-way (see Updating).
Where gameplay settings live
Difficulty, game mode, PVP, view distance, MOTD, max players, and the like are server settings in the dashboard — they apply to whatever world is loaded, matching Minecraft's own model. World-generation choices (seed, level type, structures, hardcore) belong to a world and are set when you create one.
The allowlist is always enforced — Beacon is the access manager, maintaining it over RCON from the dashboard's Players page. There's no toggle to disable allowlist enforcement; that's a deliberate safety invariant.
See Managing your beacon for the dashboard surfaces.