# Mindcraft: running an LLM-controlled bot inside Minecraft Java Edition

> Mindcraft connects a language model to a Mineflayer bot so it can mine, craft and talk in a Minecraft world. The setup is short, the model choice is wide, and the code-writing mode is the part to think about twice.

**mindcraft-bots/mindcraft** — Minecraft AI with LLMs+Mineflayer

- Repository: https://github.com/mindcraft-bots/mindcraft
- Stars: 5,816 · Forks: 940
- Language: JavaScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/mindcraft-bots-mindcraft

## What Mindcraft is for, and who ends up using it

Mindcraft is a Node.js program that puts a language model in charge of a Minecraft Java Edition character. The bot is not scripted with fixed routines. It receives the world state through Mineflayer, the JavaScript library that speaks the Minecraft protocol, and the model decides what to do next: walk somewhere, mine a block, craft an item, answer another player in chat. The README frames the project as "Crafting minds for Minecraft with LLMs and Mineflayer".

The audience follows from that. Someone who wants to see how a model behaves when its actions have consequences in a persistent world. Someone building a benchmark where the agent has to gather resources rather than answer questions. Someone teaching an agent course who needs a cheap, visible environment. The repository also carries a research framing: there is a paper website and a minecollab.md file whose instructions the README points to for running tasks.

It is not a mod, and it is not a plugin for a server. It is a separate process that joins your world as a player, which means the world has to be open to it and the account has to exist.

## How the model, the profile and the bot fit together

The architecture has three moving parts. settings.js holds project-level options such as the server host and port, the authentication mode and the insecure-coding flag. A profile file such as andy.json holds the agent's identity: its name, the model string, and the prompts that shape its behaviour. keys.json holds provider credentials, and the README notes you only need one key.

At runtime the bot connects to the world, Mineflayer exposes what the character can perceive and do, and the model's replies are turned into actions. The package list shows the shape of that layer: mineflayer-pathfinder for movement, mineflayer-collectblock for gathering, mineflayer-pvp for combat, mineflayer-auto-eat and mineflayer-armor-manager for survival chores. Those plugins are what make model output executable rather than merely conversational.

Model support is deliberately broad. The README table lists openai, google, anthropic, xai, deepseek, ollama, qwen, mistral, replicate, groq, huggingface, novita, openrouter, glhf, hyperbolic, vllm, cerebras and mercury, each with its own config variable except the self-hosted ones. The model is selected by name in the profile, for example model: "gemini-2.5-pro". That breadth is the project's strongest design decision, because it lets you swap a frontier model for a local one without touching bot code.

There is also a multi-agent path. The docker-compose.yml exposes a Mindserver port on 8080 and a range 3000-3003 for per-bot camera views, which implies several bots can run against one coordination service. The README does not explain the coordination protocol in the section shown, so treat that as something to read in the source before relying on it.

## Installing Mindcraft and getting one bot into a world

The requirements are Minecraft Java Edition up to v1.21.11 with v1.21.6 recommended, Node.js with v18 or v20 LTS recommended (the README warns that Node v24+ may cause issues with native dependencies), and at least one API key. On Windows the installer asks you to check "Automatically install the necessary tools" so native modules can build.

Start by cloning the repository or unzipping the latest release, then rename the example key file and fill in a single provider key. The README is explicit that one key is enough and that the model itself is chosen in the profile.

```bash
mv keys.example.json keys.json
npm install
```

Next, open a Minecraft world and open it to LAN on localhost port 55916, which is the default the bot expects. Then start the process from the project directory.

```bash
node main.js
```

If the bot connects, you should see it appear in the world under the name given in the profile. That name matters more than it looks: the README warns that the profile name must exactly match the Minecraft profile name, otherwise the bot will spam talk to itself.

For a local model instead of a hosted API, the README gives an Ollama command and a companion embedding model.

```bash
ollama pull sweaterdog/andy-4:micro-q8_0 && ollama pull embeddinggemma
```

To connect to an online server rather than a LAN world, the README shows editing the host, port and auth fields in settings.js, with auth set to "microsoft" and port 55920 in its example. The account used is whichever one the Minecraft launcher is currently signed into, so you switch to the bot account, start the process, then switch back.

## Tasks, goals and the JSON that drives them

Beyond free-form play, Mindcraft has a task mode where the bot starts with a prompt and a concrete goal such as acquiring an item or constructing a blueprint. The README gives this invocation for a basic single-agent task:

```bash
node main.js --task_path tasks/basic/single_agent.json --task_id gather_oak_logs
```

The task file is JSON keyed by task id, and the example shown in the README carries a goal string, an initial_inventory map, agent_count, a target item, number_of_target, a type of "techtree", max_depth and depth values, a timeout, blocked_actions per agent, missing_items and a requires_ctable flag. That structure is the interesting part: it describes a small dependency graph rather than a script, so the agent has to work out the intermediate steps. The README's example asks for four oak logs with a wooden axe already in inventory, a timeout of 300 and depth 1.

This is where Mindcraft stops being a toy and becomes a harness. You can vary the goal, the starting inventory and the blocked actions, and compare how different models cope. The README does not document task result formats or how failures are reported, so anyone using it for measurement will have to read the task runner in src/ to know what is recorded.

## The code-writing mode is the real risk surface

Mindcraft can let the model write and execute code on the machine running the bot. The README puts a caution block at the top rather than in a footnote: "Do not connect this bot to public servers with coding enabled." The same block states that the code is sandboxed but still vulnerable to injection attacks, that code writing is disabled by default, and that it is enabled by setting allow_insecure_coding to true in settings.js. The project uses the SES library, which appears in the dependency list, as part of that sandboxing.

Take the wording at face value. A sandbox that the maintainers themselves describe as still vulnerable to injection is a sandbox you should treat as a containment measure, not a security boundary. The realistic failure mode is a chat message or a world object carrying text that the model treats as an instruction, and the resulting code running with your user's permissions. The default being off is the right call, and leaving it off costs you only the code-writing capability.

The second constraint is version and runtime drift. Minecraft support stops at v1.21.11, and the README recommends Node v18 or v20 while warning that v24+ may break native dependencies. Those are pinned ranges, not preferences, and a fresh machine with the current Node release will likely need a version manager before npm install succeeds.

## Docker, ViaProxy and the self-hosted path

The repository ships a Dockerfile and a docker-compose.yml, which is the cleaner route on a machine you do not want to configure by hand. The compose file mounts settings.js, keys.json, profiles and bots from the host, sets auto_open_ui to false through a SETTINGS_JSON environment variable, and publishes ports 3000-3003 for bot camera views plus 8080 for the Mindserver. The comment in the file points at http://localhost:3000/ for the view from the camera on the bot's head.

The Dockerfile is based on node:22-bookworm-slim and installs a long list of native build and graphics packages, including python3, xvfb, libgl1-mesa-dev, libosmesa6-dev, libcairo2-dev and the pango, jpeg, gif and rsvg development headers. That list tells you what the viewer and canvas dependencies need, and it is also why a bare npm install on a stripped-down machine tends to fail.

There is a second service behind a compose profile called viaproxy, using the ghcr.io/viaversion/viaproxy image on port 25568. The comment says to use it to connect to unsupported Minecraft server versions and points to services/viaproxy/README.md. If your server is newer than the supported range, that is the documented workaround rather than editing protocol code.

One honest gap: the compose file mounts keys.json from the host, so the credentials file has to exist before the container starts. There is no documented path for supplying keys purely through environment variables.

## Where Mindcraft is the wrong tool, and what to compare it against

Mindcraft is the wrong choice if you want a reliable in-game companion. The agent's behaviour is model output, so it will wander, misread situations and need supervision. Nothing in the README promises determinism, and the task format exists precisely because free play is hard to evaluate.

It is also the wrong tool if you cannot accept a separate process joining your world as a player, or if your server is a version the project does not support and you do not want to run ViaProxy in front of it. And it is the wrong tool if you wanted a Python library: the bot is JavaScript, and the only Python in the repository is requirements.txt, which pulls boto3, botocore, pandas, prettytable, tqdm and python-socketio[client]. Those are client-side helpers for talking to the bot's socket interface, not a reimplementation.

The closest comparison is Voyager, the Minecraft agent that also drives a Mineflayer bot with a language model. The difference in approach is where the intelligence is stored. Voyager builds and keeps a library of reusable skills that the agent writes, stores and retrieves, so capability accumulates across sessions. Mindcraft does not describe a persistent skill library. Its design leans on the profile prompts, the task JSON and the choice of model, and the code-writing mode is the closest thing to self-extension. That makes Mindcraft easier to reason about per run and less capable of compounding what it learned. If you want a bot that gets better at a specific world over time, that architectural difference is the one to weigh.

## Maintenance, licence and what upgrades cost you

The last push to the develop branch was on 2026-06-10, and the latest release, v0.1.4, is tagged "General Maintenance" and dates to 2026-03-20. The two releases before it, v0.1.3 "Villagers and Buckets" and v0.1.2 "UI, AI Speech, ToolUse", are from September 2025. So the release cadence is irregular and the current line is still versioned 0.1.x. The README itself says the maintainers are "currently not very responsive to github issues" and directs people to Discord and the FAQ. Plan for support through those channels rather than through the issue tracker.

Upgrade cost is dominated by the pinned dependencies. Minecraft support tops out at v1.21.11 with v1.21.6 recommended, Node is recommended at v18 or v20, and package.json pins a long list of Mineflayer plugins plus canvas, three and prismarine-viewer, with overrides forcing canvas ^3.1.0 and gl ^8.1.6. A Minecraft update or a Node major release can invalidate that combination, and the Dockerfile exists largely because rebuilding those native modules is fiddly. There is also a postinstall step running patch-package against the patches directory, so local patches are part of the install path and worth checking after any pull.

The project is MIT licensed, which is permissive and places few obligations on how you reuse or redistribute it. That covers the Mindcraft code. It does not cover the models you point it at, and the README's provider table spans commercial APIs and local Ollama models whose own terms differ. If you ship a bot built on Mindcraft, the licence question you actually need to answer is about your model provider, not about this repository.

## Conclusion

Mindcraft suits people who already run a Minecraft Java world and want to watch a language model act through Mineflayer, plus researchers who need a scriptable agent harness with task JSON and multiple profiles. It is a poor fit if you want a finished game assistant, if you cannot run Node 18 or 20, or if you plan to point it at a public server with code writing enabled. Before adopting it, verify three things: that your Minecraft version is at or below 1.21.11 with 1.21.6 recommended, that your chosen provider key is present in keys.json and the matching model name is in the profile, and that allow_insecure_coding is left at its default of false in settings.js.

## FAQ

### Is the project called Mindcraft or Minecraft?

They are different things. Mindcraft is the open source project that drives a bot inside Minecraft Java Edition through Mineflayer, while Minecraft is the game itself, published by Mojang. The repository name is mindcraft-bots/mindcraft.

### Which Minecraft version does Mindcraft support?

The README says Minecraft Java Edition up to v1.21.11, and recommends v1.21.6. For servers outside that range, the repository includes a viaproxy service in docker-compose.yml that the comment describes as a way to connect to unsupported Minecraft server versions.

### Can Mindcraft run on a local model instead of a hosted API?

Yes. The README supports ollama as a provider and gives a command to pull the project's own finetuned model, sweaterdog/andy-4:micro-q8_0, along with embeddinggemma. The model itself is selected by name in the agent profile.

### Does Mindcraft need an API key?

It needs at least one key from a supported provider, and the README notes you only need one. The default is OpenAI. You rename keys.example.json to keys.json and fill in the key for whichever provider your profile selects.

### Is it safe to let Mindcraft write and run code?

The README warns against connecting the bot to public servers with coding enabled and states that the sandbox is still vulnerable to injection attacks. Code writing is disabled by default and only turns on when allow_insecure_coding is set to true in settings.js.

## Sources

- [Issues](https://github.com/mindcraft-bots/mindcraft/issues)
- [License: MIT](https://github.com/mindcraft-bots/mindcraft/blob/develop/LICENSE)
- [mindcraft-bots/mindcraft on GitHub](https://github.com/mindcraft-bots/mindcraft)
- [README](https://github.com/mindcraft-bots/mindcraft/blob/develop/README.md)
- [Releases](https://github.com/mindcraft-bots/mindcraft/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mindcraft-bots-mindcraft