Getting Started
Install, launch, and get a server running. A native desktop app — no web panel to host, no docker-compose spelunking, no SSH-and-tail-the-log.
Step 1 → 3
Quick start
From download to a running Minecraft server in minutes.
1Install MineUI
Grab the build for your platform from GitHub Releases. Linux gets an AppImage (81.7 MB, no install — mark it executable and run) or a 7.3 MB .deb; Windows a ~6 MB setup exe; macOS a ~7.5 MB .dmg for both Intel and Apple Silicon:
$ chmod +x MineUI_2.0.0_amd64.AppImage && ./MineUI_2.0.0_amd64.AppImage
$ sudo apt install ./MineUI_2.0.0_amd64.deb
$ MineUI_2.0.0_x64-setup.exe
$ open MineUI_2.0.0_aarch64.dmg # Intel: MineUI_2.0.0_x64.dmg
The released binaries are free. Only building from source requires a HeroUI Pro license token — see Contributing. Java is only needed on the machine that runs the server (Simple mode); Advanced mode just needs Docker or Podman.
2Your first server (Simple mode)
Simple mode is the default: MineUI runs a managed vanilla server for you. Open the Create Server flow and:
- Pick a Minecraft version — MineUI downloads the official server jar from Mojang's manifest and verifies its SHA-1 before anything runs.
- Set the memory allocation for the Java process.
- Accept the Minecraft EULA — the same step you'd do by hand in
eula.txt, surfaced in the UI. - Start it. MineUI auto-configures RCON with a generated password and supervises the Java process — start, stop, restart, and crash detection are all handled.
From there the Status page shows live TPS, MSPT, players, and version, and logs stream in real time — no polling.
3Advanced mode: attach to a container
Already running your server in Docker or Podman? Advanced mode attaches to an existing container — MineUI auto-detects both runtimes (Podman first) and lists your containers to pick from.
It is attach-only by design: MineUI never creates, pulls, or deletes containers, so your compose files and images stay exactly as you wrote them. itzg/minecraft-server-style containers work well.
Guides
Feature guides
Every major surface of the app, and what it does for you.
Create a server
The stepper flow behind Simple mode: pick a Minecraft version, set memory, accept the EULA — MineUI downloads the SHA-1-verified jar, configures RCON, and supervises the Java process.
Attach a container
Advanced mode attaches to an existing Docker or Podman container (auto-detected, Podman first) with the world under /data — e.g. an itzg/minecraft-server image. It never creates or pulls containers.
Status
Start/stop/restart plus live TPS, MSPT, player count, and server version, and a log viewer streamed over native pipes — no polling.
Players
Online list, join/leave history with last-seen and IP parsed from the log stream, and one-click whitelist/op/ban/kick.
RCON console
A console restricted to an allowlisted command set — only vetted commands ever reach the server, even with raw RCON configured.
Mods & plugins
Browse installed jars, upload from disk (source-validated), or download from a URL (SSRF-hardened). Server-utils upgrades the list to the true loaded-mod list.
Config editor
Edit server.properties and files under config/ in-app. A path allowlist keeps every edit inside the server directory.
Backups
World snapshots as portable .tar.gz archives — create, list, restore, and delete from the Backups page.
Metrics
CPU, memory, and disk for the server process, plus network/block IO when attached to a container. Server-utils adds tick-based TPS/MSPT and per-dimension chunk/entity counts.
Server utils
Optional Forge 1.20.1 mod / Paper plugin inside the server JVM exposing an authenticated HTTP API (default 127.0.0.1:8787). Set its URL in Settings for enriched metrics.
Themes & sound
Four themes — Deepslate & Emerald (default), Phosphor Amber, Quantum Fluidity, Soft Glass — with bundled offline fonts and Howler-driven UI sound.
Settings
Container runtime override (Podman/Docker), server-utils URL and token, theme selection, and sound preferences — persisted locally.
Optional companion
MineUI Server Utils
A small mod inside the server JVM that upgrades MineUI's metrics from educated guesses to ground truth.
mineui_server_utils (v0.2.0) ships as a Forge 1.20.1 mod and a Paper plugin. Drop it into your server's mods/ (Forge) or plugins/ (Paper) folder — it is not a standalone jar and needs JDK 17. It exposes an authenticated HTTP API on 127.0.0.1:8787 with these endpoints: /health, /properties, /players, /tps, /metrics, /mods, and /status.
With it installed, MineUI reads real tick TPS and MSPT, per-dimension chunk and entity counts, the true mod list, and cgroup metrics. Without it, MineUI still works — it falls back to server-list ping plus container/process metrics.
Security notes: binding to anything other than loopback requires setting MINEUI_SERVER_UTILS_TOKEN, and responses strip all rcon.* keys so the RCON password never crosses the wire.
Transparency
Where your configs live
MineUI edits real files in real places — behind a path allowlist — so you can always inspect, back up, or hand-edit them.
server.properties
enable-rcon=true
rcon.port=25575
max-players=20
white-list=trueconfig/ directory
config/
├── paper-global.yml
└── <mod or plugin configs>MineUI app data
Linux ~/.local/share/studio.i4c.mineui/
Windows %APPDATA%\studio.i4c.mineui\
macOS ~/Library/Application Support/studio.i4c.mineui/Server utils (optional)
# Non-loopback binding refuses to start without a token
MINEUI_SERVER_UTILS_TOKEN=<secret>
# rcon.password / rcon.port / query.port are
# always stripped from API responsesReference
Pages reference
Every page of the app with its capabilities. 8 pages, one click away.
Status
Server control and live health in one place — lifecycle buttons, tick metrics, and the streamed log viewer
Capabilities
Quick access
Status → Restart
TPS 20.0 · MSPT 4.2 · 3 players
Players
Online list plus join/leave history parsed from the log stream, with one-click moderation
Capabilities
Quick access
Players → select a player → Whitelist
RCON
An allowlisted RCON console — only vetted commands run, even with raw RCON access configured
Capabilities
Quick access
rcon> tps
rcon> whitelist add Steve
Mods
Browse installed mods and plugins, upload a jar from disk, or download one from a URL
Capabilities
Quick access
Mods → Download from URL
Config
Edit server.properties and files under config/ without leaving the app
Capabilities
Quick access
Config → server.properties → enable-rcon=true
Backups
World snapshots as portable .tar.gz archives — create, browse, restore, delete
Capabilities
Quick access
Backups → Create backup
world-2026-07-25.tar.gz
Settings
Runtime, integration, and appearance settings — persisted locally
Capabilities
Quick access
Settings → Server utils URL → http://127.0.0.1:8787
Create Server
The Simple-mode stepper — from nothing to a running vanilla server without a terminal
Capabilities
Quick access
Create Server → pick version → set memory → accept EULA
When things break
Troubleshooting
Known issues and their fixes — most are already shipped, so updating usually solves it.
The managed server won't start — EULA not accepted
Mojang requires accepting the EULA before a server will boot. The Create Server stepper has an explicit EULA step — go back through it, or set eula=true via the Config page, then start the server again.
Podman isn't detected in Advanced mode
MineUI talks to Podman through its socket, which many distros don't start by default. Run systemctl --user enable --now podman.socket and re-open Settings. If you run both runtimes, note Podman is tried first — use the manual override in Settings to force Docker.
No container shows up to attach to
Advanced mode attaches to an existing Minecraft server container — it never creates or pulls one. Start a container whose world lives under /data (e.g. itzg/minecraft-server) first: docker run -d -e EULA=TRUE -v ./data:/data -p 25565:25565 itzg/minecraft-server, then retry.
RCON connection refused
Check server.properties: enable-rcon=true, a non-empty rcon.password, and that rcon.port (default 25575) is reachable from the app. In Simple mode MineUI configures RCON when it creates the server; for attached containers you may need to set these yourself and restart the server.
The AppImage won't start on Linux
Make it executable first: chmod +x MineUI_2.0.0_amd64.AppImage. If it still fails, your distro may be missing FUSE (needed by all AppImages) — install libfuse2/fuse, or use the deb package instead.
Enriched metrics (tick-based TPS/MSPT, chunk/entity counts) are missing
Those come from the optional mineui_server_utils mod/plugin. Verify it's installed in the server (JDK 17 required) and that Settings → Server utils URL points at it (default http://127.0.0.1:8787 — try curl http://127.0.0.1:8787/health). If it binds a non-loopback host, MINEUI_SERVER_UTILS_TOKEN must be set or it refuses to start. Without it, MineUI falls back to server-list ping + container/process metrics.
Still stuck? Open an issue — include your platform, the mode you're in (Simple or Advanced), and the server log around the failure.
AGPL-3.0
Contributing
Issues and PRs are welcome at github.com/I4cTime/mineui. MineUI is AGPL-3.0-only; the released binaries are free — building from source needs a HeroUI Pro license token.
# Prerequisites: pnpm, Rust (rustup), and a HeroUI Pro token $ git clone https://github.com/I4cTime/mineui && cd mineui $ pnpm install $ pnpm tauri dev # Production desktop bundle $ pnpm tauri build
The Rust core (mineui-core) carries the test suite — 84 tests behind 31 typed IPC commands. Without a HeroUI Pro token, pnpm install appears to succeed but @heroui-pro/react resolves empty and the build fails. Start with the README, and if MineUI saves you time, there's a Ko-fi.
Ready to run your server?