Minecraft Helper Bots¶

Swarm Hosts can run short, bounded helper sessions on eligible Minecraft Java deployments. The Bots page uses server-owned profiles and safety rules; it does not accept arbitrary servers, plugins, commands, or behavior code.

Before you start¶

All of these conditions must be true:

• the deployment is Minecraft Java and is running;
• the Minecraft Java status check shows reachable;
• Authenticate with Mojang is off;
• no other deployment action is still queued; and
• your deployment role includes manage access.

Swarm Hosts chooses the verified endpoint for the current deployment. A bot session cannot target another Swarm Hosts deployment or a third-party server.

Available profiles and limits¶

Profile	Default / maximum bots	Default length	Reconnect	What it can do
Observer	1 / 5	5 minutes	Off	Join and remain visible without moving, chatting, fighting, or changing the world.
Greeter	1 / 3	3 minutes	Off	Send one fixed, bot-labeled welcome line per helper. It cannot accept free-form chat or slash commands.
Patrol	1 / 1	3 minutes	Off	Walk one four-point route within four blocks of its join position, then stop. It cannot dig, place, bridge, or use parkour.
Survival helper	1 / 1	5 minutes	Off or replace lost	Eat safe food and equip armor already in its own inventory. Replacement is capped at two reconnects. It cannot open containers, fight, build, or mine.

The advanced controls offer session lengths of 1, 3, 5, or 10 minutes. Ten minutes is the server-enforced maximum. Each profile also enforces its own bot count and reconnect choices even if someone submits a modified form.

Builder sandbox and Miner sandbox are visible so their intended safety boundary is clear, but they are unavailable. Customer sessions cannot start either profile until separate placement/mining and world-cleanup proof passes.

Start a session¶

1. Open the running Minecraft deployment.
2. Choose Bots.
3. Read the profile's limits and select a profile. Start with Observer when checking a server for the first time.
4. Optionally open Advanced session limits to choose an allowed bot count, session length, and reconnect rule.
5. Choose Start bots.

The page refreshes active sessions automatically. Compare Desired bots with Online now, review Last reconcile, and expand Events and artifacts when a session does not behave as expected.

Status meanings¶

Status	Meaning	What to do
Waiting to start	The request is saved, but the deployment action queue was not clear.	Wait for the other action to finish, refresh, then choose Start now on the session.
Starting	Swarm Hosts queued the helper runtime and is waiting for its result.	Wait for a join or error event. Do not submit duplicate sessions.
Running	The runtime reported an active session.	Check desired and online counts plus profile-specific events.
Reconnecting	A Survival helper is making a bounded replacement attempt after a disconnect.	Wait for a join or terminal event. The session cannot reconnect indefinitely.
Stopping	A stop request is in progress.	Wait for Stopped, Failed, or Timed out before cleanup.
Stopped	The session exited after a stop request or normal shutdown.	Choose Clean up after saving any support details you need.
Failed	The runtime reported a blocker or error.	Expand events, record the visible blocker, then clean up before retrying.
Timed out	A session or bounded behavior exceeded its deadline.	Record the last movement/action event, then clean up.
Cleaned up	Swarm Hosts recorded the session's bot disconnection and resource removal.	Confirm active, desired, and online counts return to zero.

Event and artifact meanings¶

The latest five events appear on each session card.

Event	Meaning
Start or Lifecycle	Swarm Hosts accepted the request or recorded a state transition.
Join	A helper joined the verified Minecraft endpoint.
Chat	Greeter emitted its fixed welcome line.
Movement	Patrol reported a target, reached point, stuck recovery, or timeout.
Action	A bounded Survival helper decision was recorded.
Stop	Shutdown was requested or observed.
Cleanup	Bot disconnection and session-resource cleanup were recorded.
Error	A blocker prevented the requested behavior or made the session fail.
Diagnostic	Sanitized runtime context was recorded for support.

Artifacts are sanitized evidence records such as a runtime report identifier or checksum. Their presence does not override a failed status or prove that cleanup completed; use the lifecycle status and cleanup event together.

Stop and clean up safely¶

Use Stop all bots immediately if a helper moves, chats, reconnects, or stays online unexpectedly. To finish cleanup:

1. Choose Stop all bots, or Stop session on one session card.
2. Wait until every session is Stopped, Failed, or Timed out.
3. Choose Clean up on every terminal session.
4. Confirm Active sessions, Desired bots, and Online now are all zero.
5. Confirm the Minecraft Java status check is still reachable before starting another session.

Do not repeatedly press Start or Stop while an action is queued. If a helper is still visible after the page reports cleanup, stop creating sessions and contact support with the safe details below.

Common blockers¶

Message or symptom	Check
Deployment must be running	Start the Minecraft deployment and wait for its launch action to finish.
Minecraft check is not reachable	Resolve the Java status/relay problem first; a TCP-only check is not enough.
Mojang authentication is on	Use bots only on a private/test deployment already intended to run without online authentication.
Deployment manage access is required	Ask the deployment owner for an admin role. View access can inspect state but cannot start, stop, or clean up.
Another action is queued	Wait for the pending deploy, restart, import, backup, or other action to finish.
Builder or Miner validation pending	This is an enforced product limit, not a browser-only disabled button.
Failed or timed out	Save the visible blocker, recent events, artifact IDs, and last reconcile time; clean up before one careful retry.

Not supported in this release¶

• Microsoft/Mojang-authenticated bot accounts or public-server use;
• arbitrary target hosts, ports, or third-party servers;
• Builder, Miner, combat, container access, or unrestricted world changes;
• free-form or AI-generated chat, slash commands, player impersonation, or customer-provided scripts/plugins;
• open-ended autonomous goals, LLM planning, or learned skills; and
• unlimited bot counts, durations, reconnects, or background sessions.

Future curated-intelligence research is not part of the shipped helper-bot feature.

Ask for help¶

Include the deployment ID in a private support channel, the last eight characters of the session ID shown on the card, profile, status, visible blocker, last reconcile time, and the latest event types. Do not post tokens, cookies, RCON passwords, .env files, raw request headers, private host addresses, or unredacted logs.

Use the Support Checklist for the full safe report format. Support operators can follow the Minecraft Helper Bot Support Runbook.