Quick Start

Five minutes from zero to a running Minecraft server.

Prerequisites

Home Assistant OS or Supervised
A modern 64-bit HA host (Pi 4/5, x86 NUC, or any 64-bit server). Java comes bundled in the add-on (Eclipse Temurin JRE 25) — you don’t install it — but it needs 64-bit hardware, so older 32-bit ARM boards won’t work.
~2 GB free RAM beyond what HA itself uses (4 GB+ for plugin-heavy setups)

Install it

Add the repository. In Home Assistant: Settings → Add-ons → Add-on Store → ⋮ → Repositories, then paste:
Repository URL
```
https://github.com/bruhautomation/BRUH-HA-Apps
```
Install the add-on. Find BRUH Minecraft in the store and click Install (~600 MB image).
Accept the EULA. Open the Configuration tab and set:
```
eula: true
```
This acknowledges the Minecraft EULA — required by Mojang. (The panel’s first-run wizard walks you through the same acceptance plus the first world’s settings — online/offline mode, server software, gamemode — if you’d rather click than edit YAML.) While you’re there, you’ll likely want:
- memory_mb: 4096 if you’ll have more than ~5 players or any plugins
Gameplay settings (difficulty, gamemode, online-mode, …) are per-world — the wizard sets them up front, and the panel’s Server Properties tab edits them any time. For LAN-only / no-Xbox-account play, see Family mode below. To OP yourself: join once, then click op next to your name on the panel’s Players tab.
Start. Click Start and watch the Log tab — Paper takes ~30 seconds to reach Done. After the integration discovery prompt, click Configure in Settings → Devices & Services.
Connect. Java players use <your-HA-host>:25565. Bedrock players (iOS, Android, console, Win10/11) use <your-HA-host>:19132 — and the server also auto-appears in the Friends tab on the same LAN. The panel’s dashboard shows the player count tick up as people join.

Family mode (no Xbox required)

Want kids to join without Microsoft accounts? Pick offline mode in the first-run wizard’s connectivity step — or flip it later on the panel’s Server Properties tab:

online-mode=false

That’s the whole change. The add-on then fixes every downstream setting Microsoft and GeyserMC normally gate behind that one flag — secure-profile enforcement, Geyser auth-type, Floodgate, Bedrock login validation. Java and Bedrock both work without Xbox sign-in.

LAN-only. Offline mode is unsafe on a public/internet-exposed server — anyone who guesses a username can join as that player.

Open it to the internet

Forward these on your router to your HA host:

Port	Why
`25565/tcp` + `25565/udp`	Minecraft Java
`19132/udp`	Minecraft Bedrock

Don’t forward 25575 — RCON is loopback-only by design.

Common first-install hiccups

Symptom	Fix
`EULA has NOT been accepted`	Set `eula: true`.
`address already in use: 25565`	Another server’s running. Stop it, or change the port mapping.
Bedrock not in Friends tab	Same subnet/VLAN as HA? Try `<HA host IPv4>:19132` manually.
iOS hangs on “Connecting…”	Set `geyser_mtu: 1200`.
Plugin install warning, server still starts	A bad URL in `plugins:`. Add-on logs which one — fix or remove it.

For more, see the Reference.