Minecraft Java¶

Minecraft Java is the recommended first Swarm Hosts server. It runs over TCP and stores its server data under /data. Swarm Hosts waits for the TCP socket to open before marking the deployment as fully running, then the deployment detail page uses a Minecraft Java status check to confirm the player-facing endpoint. On Windows hosts using the native process fallback, this same management flow is routed through the native runtime contract in the experimental parity slice.

Basics you should know¶

• Default protocol: TCP
• Typical port: 25565/tcp
• Persistent data: /data
• World data: usually /data/world

Recommended launch settings¶

1) Open Launch. 2) Choose Minecraft Java. 3) Pick the server type. Use Vanilla Minecraft unless you know you need Paper, Fabric, Forge, NeoForge, Quilt, or Purpur. 4) Leave Minecraft version as LATEST for the newest stable Java server supported by the image, or pin a specific Java version when your group needs one. 5) Keep Java memory at or below the container memory limit you choose in the UI. 6) Adjust the guided settings for game mode, difficulty, max players, view distance, simulation distance, PVP, online authentication, whitelist, Nether access, and command blocks. 7) Click Launch.

Common paths¶

• Server properties: /data/server.properties
• World: /data/world
• Logs: /data/logs
• Plugins / mods / packs: image-dependent, but most server-managed content is persisted under /data

Install a Modrinth modpack¶

Minecraft deployment details include a Modpacks tab for Modrinth .mrpack server packs. Swarm Hosts saves the selected Modrinth version to your library, caches the archive on the swarm host, and then installs it into the deployment data folder through the agent.

1) Open the Minecraft deployment and stop the server. 2) Open Modpacks. 3) Search Modrinth by pack name. Use the Minecraft version and loader filters when your server must stay on a specific Fabric, Forge, NeoForge, or Quilt version. 4) Choose View versions, then save or cache the exact version you want. Caching downloads the .mrpack archive to the swarm host and verifies the Modrinth file hashes before marking it ready. 5) After the cache status is Ready, choose Install from Library and host cache. If the host supports deployment backups, Swarm Hosts queues a safety backup first, then installs the cached pack. 6) Start the server after the install job finishes, then wait for the Minecraft Java status check before inviting players.

Installing a pack writes server-supported files from the .mrpack, applies overrides/ and server-overrides/, and records an installed-modpack manifest under /data/.swarm/modpacks/installed-modpack.json. Client-only files marked as server-unsupported are skipped.

Install only packs you trust. Third-party Minecraft mods run code inside the game server process and can affect server stability, performance, and player data. Keep a fresh backup before changing large packs or switching loaders.

Give items on modded servers¶

Minecraft deployment details include a Give item admin action. Swarm Hosts validates the selected players, item id, quantity, and safety policy before it generates /give commands server-side.

For vanilla servers, the picker uses the built-in static Minecraft item catalog. For modded Fabric, Forge, NeoForge, or Quilt servers, Swarm Hosts can use a server companion item-registry report when one is available. A fresh companion catalog lets the picker find non-minecraft namespace items by display name, registry id, namespace, and source/mod metadata. If the report is missing or stale after a restart or modpack change, Swarm Hosts falls back to vanilla-only item validation and blocks modded item ids until you refresh the catalog.

Import an existing world¶

Minecraft deployment details include an Import tab for bringing in a world or server folder from your current computer or from a path that already exists on the swarm host.

1) Open the Minecraft deployment, then Import. 2) Choose Upload a world/server folder from this computer for the normal local-world path. The browser sends files directly to the swarm host through the File Manager gateway/WebRTC transfer path; world file bytes are not sent through the control plane. 3) After upload, Swarm Hosts stages the folder under a hidden .swarm-imports/<upload-id>/ path on the swarm host, fills that source path, and queues the normal import preview. 4) Review the detected world name, layout, server.properties status, size, and validation messages. Native-path imports preserve existing values such as level-name when applying managed Swarm settings. 5) Confirm replacement to create a safety backup of the current deployment data and import the previewed source.

Use Advanced/manual swarm-host path when the source already exists on the host or when the browser cannot use direct folder upload. Common examples include /home/minecraft/server-backup, /srv/minecraft/worlds/Survival, C:\Minecraft\server-backup, and D:\Servers\Minecraft\world.

Native runtime paths route import preview/apply through the same deployment action surface used by container-backed hosts.

The import action supports swarm-host folder paths. A valid source can be a full server folder with server.properties and a world folder containing level.dat, or a single world folder containing level.dat. Invalid folders are rejected before the deployment data is changed.

Direct-to-host upload staging folders are temporary. Successful imports remove the staged .swarm-imports/<upload-id>/ source when safe, and abandoned staged uploads are cleaned up automatically after the host retention window, which is 24 hours by default. If the host reports a cleanup error, remove the staged folder from File Manager or check filesystem permissions on the swarm host.

Back up and restore a world¶

Open the Minecraft deployment, then Backups, to create a manual backup or enable scheduled backups for the deployment data folder. For Minecraft Java, Swarm Hosts archives the deployment /data folder, including the usual /data/world folder, server.properties, logs, plugins, mods, and other server-managed files stored under /data. Native Windows fallback deployments use the same backup/restore action surface through the process runtime.

The deployment detail page shows the latest backup status, the last successful backup timestamp, restore-point health, backup counts, and the archive size when the agent reports it. You can create a backup while the Minecraft deployment is running or stopped. Running backups use the current files on disk; for large or busy worlds, stop the server first when you need the quietest possible snapshot.

Scheduled backups use a conservative daily default and keep five scheduled restore points unless you choose a different interval or retention count. The retention limit applies to backups created by that schedule; manual backups stay visible until you delete them. If a scheduled backup fails, the Backups page and copyable diagnostics show a plain-language reason and next step without exposing host tokens or private environment values.

Restoring a backup in place is destructive: it replaces the current deployment /data folder with the selected backup archive. The dashboard requires an overwrite confirmation before it queues the restore. Create a fresh backup first if you might need to return to the current world state.

Use Restore as new deployment when you want a separate copy of the world, when you are migrating the world to another eligible swarm host, or when you want to validate an upgrade without overwriting the current server.

Backup archives are stored by Swarm Hosts outside the game container. They do not include Swarm Hosts host tokens, user API tokens, kubeconfigs, or the control-plane environment. They can include game-side files that live under /data, so treat downloaded archives as private server data.

Player connection info¶

Open the deployment detail page and use the compact connection panel in the deployment header. It shows the best player-facing address first:

• relay address and port when a managed relay route is active;
• otherwise the swarm host public IP and assigned TCP port for direct host networking.

For direct host networking, the address looks like:

<HOST_PUBLIC_IP>:<PORT>

Use Copy address after the Minecraft Java status check passes. Friends can paste that address in Minecraft Java Edition under Multiplayer, then Direct Connection or Add Server.

If the connection panel says the server is still starting, booting, not verified, or unreachable, do not promise friends can join yet. Keep checking logs and public reachability until the Minecraft Java status check passes. A generic TCP/public check is not enough for Swarm Hosts to mark a Minecraft server ready for players.

The deployment overview also shows Minecraft protocol. That row is the latest persisted post-deploy status proof from the public probe worker. It records whether the relay or direct public endpoint answered the Java status protocol, when it was checked, and the version, player counts, and MOTD text when the server returns them. If the proof is stale, Swarm Hosts treats the server as running but not verified until the next status validation passes.

Recover a failed or stuck deployment¶

When a Minecraft deployment fails, stays queued too long, or reaches a player-facing status-check failure, the deployment detail page shows a Common fixes for this Minecraft deployment panel.

Use the panel before collecting manual logs:

1. Retry the deployment/start action if the launch failed or appears stuck.
2. Start a stopped server when an existing container is available.
3. Restart an existing container when Minecraft started but the server is wedged.
4. Prune unused container images when image pulls fail or runtime storage is tight.
5. Force-update the swarm host agent only when the host reports that automatic updates are supported and the agent is online.
6. Copy diagnostics if the first safe action does not resolve the issue.

The panel also shows unavailable repairs. For example, Docker/containerd runtime cache resets are not offered from the deployment page because they can disrupt active containers and require explicit support confirmation.

The deployment page keeps a recent repair-attempt history with queued, running, succeeded, failed, unavailable, and superseded outcomes when Swarm Hosts has that status. The copied diagnostics include the friendly failure explanation, suggested next step, redacted recent logs, common-fix availability, and recent repair attempts so support can avoid asking you to repeat the same action.

Guided settings¶

Swarm Hosts writes common Minecraft Java settings through the launch and deployment settings forms so you do not need to edit server.properties for routine setup:

UI setting	Minecraft/env setting	Notes
Server type	TYPE	Starts with Vanilla Minecraft; mod/plugin loaders may need matching files in /data.
Minecraft version	VERSION	LATEST follows the newest stable server supported by the image; pin a version for long-running worlds.
Java memory	MEMORY	Use the safe presets in the UI and keep the heap below the deployment RAM limit. On native Windows fallback, MEMORY maps to JVM heap size while CPU is currently a Docker-required scheduling signal.
Server message	MOTD	Appears in the Multiplayer server list.
Game mode	MODE	Survival, Creative, Adventure, or Spectator.
Difficulty	DIFFICULTY	Peaceful, Easy, Normal, or Hard.
Max players	MAX_PLAYERS	Bounded in the UI to avoid accidental oversized servers.
View distance	VIEW_DISTANCE	Higher values use more CPU and memory.
Simulation distance	SIMULATION_DISTANCE	Higher values can make farms and entities more expensive.
Pause when empty	PAUSE_WHEN_EMPTY_SECONDS	Defaults to 60 seconds; set -1 for always-on servers that must keep answering status probes.
Player combat	PVP	Enables or disables player-versus-player damage.
Authenticate with Mojang	ONLINE_MODE	Keep enabled for public servers unless you fully understand offline-mode risk.
Whitelist	ENABLE_WHITELIST	Pair with the Minecraft tools on the deployment detail page to add players.
Nether	ALLOW_NETHER	Disables Nether access when turned off.
Command blocks	ENABLE_COMMAND_BLOCK	Leave disabled unless the world needs command-block automation.

Update settings after launch¶

Open the Minecraft deployment, then Configure and Minecraft settings. The settings UI is for safe managed server.properties values such as MOTD, difficulty, max players, game mode, whitelist enforcement, view distance, PVP, Nether access, and command blocks.

Use Safe presets when you want Swarm Hosts to choose matching Java memory and max-player values for common server sizes. Presets only change MEMORY and MAX_PLAYERS; saving still validates every managed value and queues the same redeploy/restart as a manual settings update. Higher presets are disabled until the deployment has enough RAM limit for the requested Java heap plus overhead.

Saving Minecraft settings queues a redeploy/restart. Swarm Hosts persists the new values in the deployment config, then the Minecraft image applies those managed values to /data/server.properties during startup. Players should wait until the deployment is running and the Minecraft Java status check passes before rejoining or sharing an invite.

The dashboard-managed settings intentionally overwrite the matching server.properties keys on restart. Use the file manager only for advanced settings that Swarm Hosts does not manage yet, and keep a backup before manual changes.

Operator and whitelist membership are separate from the whitelist on/off setting. Open Actions and use Minecraft tools while the server is running to make or remove operators, add or remove whitelist players, or list the current whitelist through RCON. If the server is stopped, already has a queued action, or RCON is disabled, the tool buttons stay disabled and explain what must change first.

The Common actions panel adds typed command templates for routine Minecraft administration without exposing a raw command box. Operators and admins can preview server-generated commands for broadcasts, XP grants, healing/feed effects, weather, time, and difficulty changes. Admin-only templates cover teleport, game mode, clear inventory, kick, ban, pardon, and whitelist changes; dangerous templates request approval before Swarm Hosts sends the generated RCON commands. Deployment admins can save named presets over those built-in templates with typed variables, then update or delete the presets later. Task history and audit details keep the template id, saved-template snapshot, variables, preview, approval decision, generated commands, and per-command result.

The same Minecraft tools panel includes Give item for running servers. It loads cached server player records, shows UUID/world/dimension/last-seen metadata when available, and lets you search by username or UUID. The server player list loads automatically and keeps refreshing while the panel is visible, with a retry button only for error recovery. Online targets queue server-generated /give commands for the selected item and quantity. The generated command preview refreshes automatically as you change players, item, quantity, reason, schedule, or advanced item-template fields; the queue button stays disabled while preview validation is pending or failed. Turn on Offline item delivery in Minecraft launch/settings when you want Swarm Hosts to start the image-local join watcher. With that capability enabled, offline cached players with UUIDs can be selected and are stored as pending deliveries until the player joins. Full-inventory delivery attempts stay pending so you can retry later or cancel the task without editing player data files. Queue online players and pending offline deliveries as separate Give Item tasks so immediate grants and next-join deliveries have separate audit records. The Give Item panel links to the deployment-scoped audit log for prior grants; the Actions page no longer keeps a separate Give Item history table. The image-local /opt/swarm-support/offline_delivery_watcher.py watches Minecraft join logs, calls /opt/swarm-support/offline_delivery.py, fetches the pending UUID-backed grants from Swarm Hosts, runs the server-generated RCON command, and reports success, failure, or full-inventory retry state through a scoped deployment token.

The item selector ranks exact and prefix matches first, supports keyboard navigation, and keeps local recent and favorite items for repeat admin workflows. Vanilla servers use the built-in static item catalog. Modded servers can use a fresh companion item-registry report to expose server-specific items with non-minecraft registry ids; stale or missing reports fall back to vanilla-only validation. If Swarm Hosts has no cached player names yet, the panel shows a loading, empty, or error state instead of asking you to type raw commands.

Deployment admins can open Advanced item template for compatible servers. Advanced templates add structured display names, lore, vanilla enchantments, damage, and unbreakable flags to the server-generated /give command. Swarm Hosts enables the editor for vanilla items when the deployment reports a Minecraft Java 1.20.5+ runtime version. For server-specific modded item data, a fresh companion catalog must explicitly report advanced item data support. Operators can keep using the simple Give Item flow, but advanced templates require deployment admin access and are validated server-side; raw NBT, raw component blobs, and client-supplied command previews are rejected.

Use Saved kits in the same panel to create reusable item presets or multi-item kits from vanilla catalog items. Each saved kit has a name, item quantities, grant/edit role limits, and a versioned snapshot. Granting a kit expands automatically into a generated preview for every selected online player and every item in the kit, then queues those server-generated /give commands through the same Admin Actions task history and audit trail as single-item grants. Editing or deleting a saved kit does not change old task records; historical entries keep the kit snapshot that was queued at the time. Admin-created item presets can include an advanced item template; granting those presets also requires deployment admin access unless a future companion capability adds a narrower delegated workflow.

Give Item and saved-kit grants can run immediately, run once at a scheduled time, or repeat on a fixed interval. Scheduled admin actions show their next run, run count, offline policy, and pause/resume/stop/cancel controls from the task detail page. If the server is offline at the scheduled time, the selected offline policy decides whether Swarm Hosts fails the task, retries later, or keeps waiting until the Minecraft server is running.

Large or policy-sensitive grants can require approval before Swarm Hosts sends the generated RCON commands to the server. Deployment admins see approval notifications, can approve or reject from the task detail page, and can leave an approval note. Task comments and the activity feed stay with the admin action record so operators can coordinate follow-up without losing the generated command history.

Run safe helper bots¶

Open a running Minecraft deployment and choose Bots. Swarm Hosts offers server-owned Observer, Greeter, Patrol, and Survival helper profiles instead of plugin names or raw behavior settings. The feature currently requires a private/test deployment with Authenticate with Mojang turned off, a reachable Minecraft Java status check, and deployment manage access.

The Minecraft Helper Bots guide lists each profile's exact bot count, default duration, reconnect policy, lifecycle/event meanings, stop/cleanup steps, common blockers, and unsupported behavior. The core safety boundaries are:

• Observer joins without moving, chatting, building, mining, or fighting.
• Greeter sends one fixed welcome line per helper. Free-form chat and slash commands are not accepted.
• Patrol walks one bounded route near its join position. It cannot dig, place blocks, bridge, or use parkour, and it stops on a timeout or repeated stuck state.
• Survival helper can use safe food and armor from its own inventory. It cannot open containers, fight players or mobs, build, or mine, and repeated danger stops the session.

Builder sandbox and Miner sandbox remain visible but unavailable while their separate placement/mining and world-cleanup proof is incomplete. Swarm Hosts also refuses crafted start requests for unavailable profiles; hiding a disabled button is not the only safety check. Bots cannot use Microsoft player accounts, target another server, accept arbitrary code, run slash commands, or use free-form/AI chat.

Use Stop all bots whenever behavior is unexpected. A stopped, failed, or timed-out session can be cleaned up from its session card. The stop and cleanup controls remain available even for sessions created by an earlier or internal workflow. Do not weaken authentication on a public server only to enable bots.

Synthetic validation traffic¶

Internal validation helpers remain available for development and runtime proof.

Operators can generate lightweight Minecraft Java protocol activity from this repo without real player accounts:

.venv/bin/python scripts/dev/minecraft_synthetic_clients.py <HOST> <PORT> \
  --clients 4 \
  --iterations 5 \
  --spawn-interval 0.25 \
  --login-hold-seconds 1 \
  --json

The tool opens real TCP connections and performs the Java server-list handshake, status request, ping packet, and a login-start probe using generated usernames such as SwarmBot001. It stops before Mojang/Microsoft account authentication; online-mode servers should report encryption_required, while offline/test servers may get as far as login_success.

This helper is not a full joined-player load test. For the researched Mineflayer-based direction for real synthetic player activity, see the Minecraft synthetic player activity research note.

Useful flags:

• --skip-login: status and ping only.
• --skip-status: login-start probes only.
• --protocol-version <N>: advertise a specific Java protocol version in the handshake.
• --login-packet name: use the older Login Start payload shape if a legacy server closes before responding.

Use this only against Swarm Hosts deployments, local servers, or other endpoints you are authorized to test. Increase --clients, --iterations, and --spawn-interval gradually so validation traffic does not look like abuse.