minecraft-agent-harness

LLM agents that play Minecraft.

Quickstart · Configuration · Tools · Teams · Bed Wars example

Point an LLM at a Minecraft server and give it something to do. It plays through Mineflayer, so it walks, mines, crafts, builds, fights and chats like a regular player. pi handles the model session. We've run Bed Wars matches with it, and a survival server with 50 agents on it at once.

What's in here:

• Claude, GPT, Gemini, OpenRouter, or your own endpoint if it speaks the OpenAI Responses API
• Sessions that survive restarts. Kill an agent, start it again under the same name, and it carries on
• A shell for every agent (Docker, E2B or a plain local folder). Agents keep notes there and write little scripts that call their own game tools
• Teams from a single JSON file, with DMs between agents and an optional shared machine
• Vision, if you want it (experimental)

Quickstart

You'll need Node 22.19+, an API key for some model provider, and a Minecraft server. If you don't have a server, the repo comes with a dev one, which needs Java 21.

npm ci
cp .env.example .env    # add the API key for your model provider
npm run server          # Paper 1.21.6 on localhost:25565, offline mode

Then in a second terminal:

npm start -- --objective "Gather wood and build a small shelter near spawn"

That's it. The default model is GPT-6.1 Terra, and Configuration covers the other providers and how to switch.

Join localhost:25565 from Minecraft 1.21.6 if you want to watch, and /tell Agent <message> to talk to it. Its output and tool calls stream to the terminal. Ctrl+C stops it. Everything it knows lives in .agent-state/<name>/, so starting it again with the same name resumes the session.

Your own server

npm start -- --host play.example.net --port 25565 --objective "Mine iron"

Online-mode servers need --auth microsoft (you'll get a sign-in prompt). Agents assume survival; pass --game-mode if your server puts them in something else.

Docker

Fill in .env as above, then:

docker compose up

You get a Paper server on localhost:25565 and one agent. Change what it does with AGENT_OBJECTIVE in .env. State goes in the agent-state volume.

Already have a server? Just run the agent image:

docker build -t minecraft-agent .
docker run --rm -it --env-file .env -v agent-state:/data minecraft-agent --host play.example.net -o "Mine iron"

Teams

npm start -- team examples/team.json

Starts three agents who can message each other. Team config has the details. For something with rules and a referee, look at the Bed Wars example.

Configuration

Flags, environment variables (.env works) or a JSON file via --config. Flags win over env vars, env vars win over the file.

A heads-up about the shell: agents get one by default. That's E2B if E2B_API_KEY is set, otherwise Docker if it's running, otherwise a local folder, and local means commands run as you. Use --sandbox none if you'd rather they didn't have one.

More docs:

• Configuration: models, auth, sandboxes, vision, where files go
• Tools: everything an agent can do
• Architecture: how the code fits together

Development

npm run check   # lint, format, tests

CONTRIBUTING.md covers the rest.

License

MIT. Some of the skill library comes from Mindcraft and the renderer worker from prismarine-viewer; their licenses are in THIRD_PARTY_NOTICES.md.