MineBot

Ender Dragon, I will kill you.

A Minecraft agent with a mind that can improvise and a body that can be trusted.

Tell MineBot what you want in ordinary language. The model chooses a strategy, the harness keeps the thread, and a server-authoritative body does the physical work.

You: Collect 64 logs.
MineBot: reasons, acts, observes, recovers, and keeps going.

Not A Script Wearing A Chatbot

MineBot puts deterministic machinery where language models are weak: physics, precise state, long-running execution, ownership, and reflexes. It leaves goals, trade-offs, and adaptation to the model.

The model chooses from one shared capability pool. The harness preserves task continuity. The Body handles the grind inside one physical objective. Every result comes back as structured world truth.

MineBot's current lightweight Body keeps physics and fast reactions on the server through Carpet + Scarpet. A planned second, narrow-version Body runs a real Minecraft client and reuses Baritone broadly for mature physical work. Both accept success only when observed world state confirms it.

Built To Finish

Navigate. Gather. Craft. Smelt. Equip. Fight. Recover. Continue.

The current baseline has passed real-server gates for collecting 64 logs, tool-gated acquisition through diamond, navigation over real terrain, following, combat, survival preemption, death recovery, restart reconciliation, and idle wake-up. Success is measured by authoritative world and inventory changes, not by a tool claiming it succeeded.

One Mind. One Body. One Source Of Truth.

openai-agents-python runs the inner model/tool loop. MineBot owns the persistent control plane around it: tasks, context, lifecycle, progress, and governed tools. Python Body transactions complete physical objectives through JSON over RCON; Scarpet reads authoritative server state and runs planning, controllers, events, and reflexes; Carpet supplies the physical FakePlayer body.

The Brain decides what. The Body resolves how. Before physical mutation, governance refuses protected claims and ambiguous/high-risk structure evidence.

minebot/
  brain/      context, lifecycle, progress, capability registry
  app/        persistent runtime and the single composition root
  body/       navigation, work, inventory, crafting, combat, recovery
  game/       protocol, transport, governance, server-backed Body client
  contract/   shared facts and result schemas
  camera/     optional observer supervisor and recording/live fan-out

minecraft/
  server/     Scarpet controllers and the optional Fabric bridge
  camera/     observer client and shared Java protocol

tests/        unit, live Body, and real-agent gates

The Road Gets Stranger

The reliable Body and persistent agent are the foundation, not the finish line. The observer, scoped Memory, Minecraft Wiki access, and loadable Skills are now part of that foundation. The immediate challenge is purposeful action in natural terrain and one honest 30-minute integrated run. Farther out are Vision, richer providers and transport, and many-bot worlds. The two north stars remain deliberately unreasonable: beat the Ender Dragon from nothing, then learn to design and build in an open world.

Wake It Up

MineBot currently targets Python 3.13 and a Minecraft 26.1.2 Fabric server with Carpet, the MineBot Scarpet app, and local RCON enabled.

The contributor gate targets Ubuntu Linux and is developed under WSL2. Native Windows and macOS are not currently claimed; see support status.

Use a disposable local world for the developer console: it spawns and resets a FakePlayer, changes gamerules, and can seed a tiny demo patch. Install Fabric + Carpet, enable local RCON in server.properties, and place the Scarpet app in the active world's scripts directory:

enable-rcon=true
rcon.port=25576
rcon.password=test

mkdir -p /path/to/server/world/scripts
cp minecraft/server/scarpet/minebot.sc /path/to/server/world/scripts/

Start the server, then prepare MineBot:

python3.13 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .

# Anthropic, Gemini, and other LiteLLM-backed providers:
# python3 -m pip install -e ".[litellm]"

export MINEBOT_LLM_MODEL=<model>
export MINEBOT_LLM_API_KEY=<key>
# Optional for an OpenAI-compatible endpoint:
export MINEBOT_LLM_BASE_URL=<https://host/v1>

python3 -m minebot.app.console

For the managed local golden-world environment, start the server reset, provider preflight, Camera, trace/state directory, and production interactive session with one command:

minebot-local

The launcher uses the local test server defaults and your existing provider environment. For a persistent private provider profile, run minebot-local --init once and fill ~/.config/minebot/runtime.env; initialize the optional observer once with minebot-camera init.

minebot-local resets only a loopback test server and enables Camera by default. Use --no-reset to preserve the current local world or --no-camera on machines without the observer stack. Remote servers continue to use the explicit minebot.app.real_server_session entrypoint and are never reset by the launcher.

Then talk to it:

minebot> collect 3 dirt
minebot> follow me
minebot> what happened while I was away?

The local console uses 127.0.0.1:25576 with password test; keep that RCON endpoint local. Existing worlds should use the non-mutating real-server entrypoint (python3 -m minebot.app.real_server_session --help) instead of this demo console.

Run the unit suite with:

python3 -m pytest tests/unit -q

Make It More Reliable

Contributions are not limited to code. Reproducible failures, evaluation scenes, traces, compatibility fixes, and clear documentation all make MineBot stronger. Start with Contributing, then check the current support matrix. A stable failure case is a complete contribution, even without a fix.

MineBot is released under the MIT License. Minecraft is a trademark of Microsoft. MineBot is independent and is not affiliated with Mojang Studios or Microsoft.