Mindcraft 🧠⛏️

Crafting minds for Minecraft with LLMs and Mineflayer!

FAQ | Discord Support | Blog Post | Contributor TODO

‼️Warning‼️

Do not connect this bot to public servers with coding enabled. This project allows an LLM to write/execute code on your computer. While the code is sandboxed, it is still vulnerable to injection attacks on public servers. Code writing is disabled by default, you can enable it by setting allow_insecure_coding to true in settings.js. We strongly recommend running with additional layers of security such as docker containers. Ye be warned.

Requirements

• Minecraft Java Edition (up to v1.21.1, recommend v1.20.4)
• Node.js Installed (at least v14)
• One of these: OpenAI API Key | Gemini API Key | Anthropic API Key | Replicate API Key | Hugging Face API Key | Groq API Key | Ollama Installed. | Qwen API Key [Intl.]/[cn] | Novita AI API Key |

Install and Run

1. Make sure you have the requirements above.

2. Clone or download this repository (big green button)

3. Rename keys.example.json to keys.json and fill in your API keys (you only need one). The desired model is set in andy.json or other profiles. For other models refer to the table below.

4. In terminal/command prompt, run npm install from the installed directory

5. Start a minecraft world and open it to LAN on localhost port 55916

6. Run node main.js from the installed directory

If you encounter issues, check the FAQ or find support on discord. We are currently not very responsive to github issues.

Customization

You can configure project details in settings.js. See file.

You can configure the agent's name, model, and prompts in their profile like andy.json.

API	Config Variable	Example Model name	Docs
OpenAI	OPENAI_API_KEY	gpt-4o-mini	docs
Google	GEMINI_API_KEY	gemini-pro	docs
Anthropic	ANTHROPIC_API_KEY	claude-3-haiku-20240307	docs
Replicate	REPLICATE_API_KEY	meta/meta-llama-3-70b-instruct	docs
Ollama (local)	n/a	llama3	docs
Groq	GROQCLOUD_API_KEY	groq/mixtral-8x7b-32768	docs
Hugging Face	HUGGINGFACE_API_KEY	huggingface/mistralai/Mistral-Nemo-Instruct-2407	docs
Novita AI	NOVITA_API_KEY	gryphe/mythomax-l2-13b	docs
Qwen	QWEN_API_KEY	qwen-max	Intl./cn
xAI	XAI_API_KEY	grok-beta	docs

If you use Ollama, to install the models used by default (generation and embedding), execute the following terminal command: ollama pull llama3 && ollama pull nomic-embed-text

Online Servers

To connect to online servers your bot will need an official Microsoft/Minecraft account. You can use your own personal one, but will need another account if you want to connect too and play with it. To connect, change these lines in settings.js:

"host": "111.222.333.444",
"port": 55920,
"auth": "microsoft",

// rest is same...

‼️ The bot's name in the profile.json must exactly match the Minecraft profile name! Otherwise the bot will spam talk to itself.

To use different accounts, Mindcraft will connect with the account that the Minecraft launcher is currently using. You can switch accounts in the launcer, then run node main.js, then switch to your main account after the bot has connected.

Docker Container

If you intend to allow_insecure_coding, it is a good idea to run the app in a docker container to reduce risks of running unknown code. This is strongly recommended before connecting to remote servers.

docker run -i -t --rm -v $(pwd):/app -w /app -p 3000-3003:3000-3003 node:latest node main.js

or simply

docker-compose up

When running in docker, if you want the bot to join your local minecraft server, you have to use a special host address host.docker.internal to call your localhost from inside your docker container. Put this into your settings.js:

"host": "host.docker.internal", // instead of "localhost", to join your local minecraft from inside the docker container

To connect to an unsupported minecraft version, you can try to use viaproxy

Bot Profiles

Bot profiles are json files (such as andy.json) that define:

1. Bot backend LLMs to use for chat and embeddings.
2. Prompts used to influence the bot's behavior.
3. Examples help the bot perform tasks.

Specifying Profiles via Command Line

By default, the program will use the profiles specified in settings.js. You can specify one or more agent profiles using the --profiles argument:

node main.js --profiles ./profiles/andy.json ./profiles/jill.json

Model Specifications

LLM backends can be specified as simply as "model": "gpt-3.5-turbo". However, for both the chat model and the embedding model, the bot profile can specify the below attributes:

"model": {
  "api": "openai",
  "url": "https://api.openai.com/v1/",
  "model": "gpt-3.5-turbo"
},
"embedding": {
  "api": "openai",
  "url": "https://api.openai.com/v1/",
  "model": "text-embedding-ada-002"
}

The model parameter accepts either a string or object. If a string, it should specify the model to be used. The api and url will be assumed. If an object, the api field must be specified. Each api has a default model and url, so those fields are optional.

If the embedding field is not specified, then it will use the default embedding method for the chat model's api (Note that anthropic has no embedding model). The embedding parameter can also be a string or object. If a string, it should specify the embedding api and the default model and url will be used. If a valid embedding is not specified and cannot be assumed, then word overlap will be used to retrieve examples instead.

Thus, all the below specifications are equivalent to the above example:

"model": "gpt-3.5-turbo"

"model": {
  "api": "openai"
}

"model": "gpt-3.5-turbo",
"embedding": "openai"

Patches

Some of the node modules that we depend on have bugs in them. To add a patch, change your local node module file and run npx patch-package [package-name]

Citation:

@misc{mindcraft2023,
    Author = {Kolby Nottingham and Max Robinson},
    Title = {MINDcraft: LLM Agents for cooperation, competition, and creativity in Minecraft},
    Year = {2023},
    url={https://github.com/kolbytn/mindcraft}
}