macOS

Get up and running with BlockAssist in your macOS environment.

Overview

This guide explains how to install and configure BlockAssist on macOS (Intel or Apple Silicon). It walks you through setting up dependencies, configuring the Python environment, and preparing BlockAssist for local training and submission to the Gensyn Testnet.

Prerequisites

• macOS 12 or newer

• Homebrew installed (brew -v should work)

• Java

• 10–15 GB free disk space

• Hugging Face account and a token with Write scope

Use this guide to install macOS on Intel or Apple Silicon processors. Pay attention to platform-specific notes for changes in packages and dependencies.

Installation Steps

You only need to run these once per computer, and you don't need to have Minecraft installed.

Apple Silicon users (ARM): See the Java note in Step 2.

Step 1 — Clone the Repo

git clone https://github.com/gensyn-ai/blockassist.git
cd blockassist

Step 2 — Install Java (Malmo/Minecraft runtime)

Follow the Intel or ARM Java installation steps below by choosing the tab that matches your CPU architecture.

Intel

Use the project's installer for Java 1.8.0_152 (as documented in the repo).

./setup.sh

Intel systems can safely use the default Java 8 setup without modifications.

ARM (Apple Silicon)

Apple Silicon Macs should not use Java 8 binaries, as they are x86_64-only and can cause Malmo or Minecraft to crash.

Instead, install OpenJDK 11 (ARM64) and point the legacy Java-8 path at it:

brew install openjdk@11
echo 'export PATH="/opt/homebrew/opt/openjdk@11/bin:$PATH"' >> ~/.zshrc
export PATH="/opt/homebrew/opt/openjdk@11/bin:$PATH"
export JAVA_HOME=$(/usr/libexec/java_home -v 11)

# (If a zulu-8 path exists, move it aside and symlink to JDK 11)
sudo mv /Library/Java/JavaVirtualMachines/zulu-8.jdk \
        /Library/Java/JavaVirtualMachines/zulu-8.jdk.backup 2>/dev/null || true
sudo ln -sfn /opt/homebrew/opt/openjdk@11/libexec/openjdk.jdk \
              /Library/Java/JavaVirtualMachines/zulu-8.jdk

Apple Silicon systems generally load faster but require ARM-native Java 11 to avoid “Bad CPU type” errors.

Step 3 — Install pyenv

brew update
brew install pyenv

Step 4 — Install Python 3.10

pyenv install 3.10
pyenv global 3.10

Step 5 — Install required Python packages

pyenv exec pip install -U pip
pyenv exec pip install psutil readchar rich

Configuration

BlockAssist uses Hydra for configuration management. You can modify settings in the src/blockassist/config.yaml file (or the project config.yaml if present) or override them via command-line arguments.

• episode_count — Number of episodes to record. If greater than 1, a new episode will start each time you press ENTER during session recording.

• num_training_iters — Number of training iterations across all recorded episodes.

Troubleshooting

Read below for common fixes to macOS edge cases, bugs, and environment configuration issues.

If you're still experiencing problems getting BlockAssist running after exhausting the options below, please make an issue in the repository here.

Common Fixes

1. Minecraft times out while starting

Give it more time (first run can take 2–5 minutes):

MALMO_TIMEOUT=300 pyenv exec python run.py
# or, if calling Malmo directly:
python -m malmo.minecraft launch --timeout 300

Verify logs/malmo.log shows “Listening on port 10000” and both windows are open.

---

1. Java is crashing, or "Bad CPU type" on Apple Silicon / ARM

Install ARM64 Java 11 and set JAVA_HOME:

brew install openjdk@11
echo 'export PATH="/opt/homebrew/opt/openjdk@11/bin:$PATH"' >> ~/.zshrc
export PATH="/opt/homebrew/opt/openjdk@11/bin:$PATH"
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
sudo ln -sfn /opt/homebrew/opt/openjdk@11/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/zulu-8.jdk
java -version

---

1. Port 10000 already in use or stuck processes

Kill any outstanding processes, then relaunch BlockAssist then using the command.

lsof -i :10000
pgrep -fa 'java|minecraft|malmo|gradle'
pkill -f 'malmo|minecraft|gradle|java'

Be sure to re-run the app after clearing processes.

---

1. Node/Yarn version or permission errors

Install the correct version of Yarn using sudo privileges. You may need to enter your account/device's password.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.nvm/nvm.sh
nvm install 20.18.0 && nvm use 20.18.0
sudo npm install -g yarn

---

1. pyenv using the wrong Python version

Run the following command to install the correct version according to the README:

pyenv install 3.10.18
pyenv global 3.10.18
echo 'eval "$(pyenv init -)"' >> ~/.zshrc && source ~/.zshrc
pyenv exec pip install -U pip
pyenv exec pip install psutil readchar rich
pyenv exec python run.py

You can also use this in the event that there are missing packages/dependencies.

---

1. Minecraft application windows not opening

Follow the sequence below in the event that the Minecraft instance windows are refusing to open:

• Approve macOS Accessibility for your terminal app.

• Ensure Java 11 ARM64 is active (see #2).

• Increase MALMO_TIMEOUT as in #1.

• Watch logs/malmo.log while launching.

• Clear straggler processes (see #3) and retry.

---

1. Missing system utilities

If certain build tools or command-line utilities are missing on your system, install them using the commands below.

xcode-select --install
brew install zip unzip

---

Helpful Diagnostics

Use the following diagnostic commands to confirm your BlockAssist environment is configured correctly. These checks verify Python, Java, and Node installations, confirm your system’s architecture, and help identify the most common “wrong version” or “missing dependency” issues.

Quick Checks

Run this small set of commands first to make sure all major dependencies are recognized and properly configured.

This will catch most “wrong version” or “wrong architecture” issues in seconds.

python -V  
pyenv versions  
java -version && /usr/libexec/java_home -V  
uname -m  
tail -f logs/malmo.log

Extended Diagnostics

If you’re still seeing crashes or unexpected errors, run the extended set below.

Copy and paste the full output when asking for help, as it’s the fastest way to catch version mismatches or architecture conflicts.

/usr/libexec/java_home -V
java -version
node -v && yarn -v
pyenv versions && pyenv which python && python -V
file "$(which java)"

Still Stuck?

If the issue you're experiencing isn't fixable via the above steps, try this sequence of commands and modifications:

• Bump timeout to 420–600 on first run.

• Quit all Java/Minecraft/Gradle processes, then retry.

• Confirm Node 20.18.0 and ARM64 Java on Apple Silicon.

• Run cd modal-login && yarn install && yarn dev if you encounter a /scripts/node_env.sh: line 14: logs/node_env.log: No such file or directory error. Then, re-run BlockAssist using python run.py or python3 run.py.

• If you encounter an error stating "BlockAssist module not found" when attempting to check blockassist-train.log files, use pip install -e . then re-run.

If you need additional support, you can open a ticket or visit our Discord.