README.md

metadata

title: Minecraft Server
emoji: 🧱
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false

Minecraft Server (Java Edition 1.21.11)

Paper server (1.21.11, build 132) bundled with the playit.gg agent so it can be reached from a normal Minecraft client, plus a small web control panel that runs in the same container.

How the networking works

A Minecraft Java client speaks raw TCP and the Space only routes HTTPS to app_port (7860), so the two cannot meet directly. The playit agent fixes this without any inbound connectivity: it dials out to playit's relays and they proxy the public address back down that same connection. The Space only ever makes outbound requests.

Minecraft client ──TCP──> playit relay <──outbound──> playitd ──> java server :25565

Port 7860 hosts the control panel (live console, commands, stop/restart), which also keeps the Space reporting as running.

Control panel

Open the Space URL in a browser (keep it private if you want - accessing the panel is separate from joining the game):

• Live server console with auto-scroll
• Send commands (say hi, list, whitelist ..., /stop) via the input or quick buttons
• Stop (graceful, saves the world) and Restart
• Status badges: server state, RAM/uptime, playit tunnel state
• Reading logs/status is open; commands and stop/restart require a password when one is configured

Panel / API over HTTP

From a browser the panel page (/) already uses the API below. The public .hf.space gateway only reliably forwards GET requests (POST bodies get rejected or stripped of their JSON quotes), so the panel talks to the API with GET + query parameters:

# status / logs
curl https://USER-SPACE.hf.space/api/status
curl "https://USER-SPACE.hf.space/api/log?after=-10"

# run a server command
curl --get --data-urlencode "cmd=list" https://USER-SPACE.hf.space/api/command
curl --get --data-urlencode "cmd=say hello" https://USER-SPACE.hf.space/api/command

# stop (graceful) / restart
curl --get --data-urlencode "action=stop" https://USER-SPACE.hf.space/api/action
curl --get --data-urlencode "action=restart" https://USER-SPACE.hf.space/api/action

If a CONTROL_PASSWORD is set, add the header X-Token: <token> where the token is sha256("panel-control:" + CONTROL_PASSWORD), and log in first via POST /api/login for a panel session. JSON/form POST endpoints also exist (/api/command, /api/action, /api/login) for callers that can reach the container directly (e.g. from inside the Space).

Setup

1. Create a Space with the Docker SDK and push this repo.
2. Generate a playit secret key (link in the playit dashboard, "new agent").
3. Add it in the Space settings under Variables and secrets as a Secret named PLAYIT_SECRET. Do not commit it.
4. (Recommended) Add a second Secret named CONTROL_PASSWORD to lock the panel's command/stop/restart actions. Leave it unset only while testing.
5. In the playit dashboard, create a tunnel of type Minecraft Java targeting localhost:25565, then claim it with this Space's agent.
6. Copy the assigned address and port into the Minecraft client's Direct Connect / Add Server.

Configuration

Variable	Default	Notes
PLAYIT_SECRET	unset	Required for the tunnel; server still boots without it
CONTROL_PASSWORD	unset	Gives the panel Open Console / Stop / Restart a password. Leave unset = unlocked (testing only)
MC_MEM	4G	Both -Xmx and -Xms
STATUS_PORT	7860	Control panel; must match app_port

Server tuning lives in server.properties aboard the container.

Caveats worth knowing

• World persistence depends on your storage. Fresh Spaces use ephemeral storage and are reset on restart; this space mounts a Storage Bucket at /data so the world/server.properties survive rebuilds and playit/client count resets only with a rebuild.
• Offline mode is on (online-mode=false), so any username can join and nothing is verified with Mojang. Turn it on if you want real authentication.
• Server jar is Paper 1.21.11 (build 132, Java 21 bytecode). The Paper bundler re-downloads the Mojang 1.21.11 server jar into versions/ on first boot. It runs on the pinned eclipse-temurin:25-jre-jammy (Java 25) base image since newer JVMs run older class files. Swap server.jar and reuse MC_JAR if you change versions.
• The server auto-restarts on crash (3s backoff) and restarts if the container is recreated, so a failed boot loops in the logs - read the newest trace.