# macOS

## 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

{% hint style="warning" %}
Use this guide to install macOS on Intel or Apple Silicon processors. Pay attention to platform-specific notes for changes in packages and dependencies.
{% endhint %}

### 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

```bash
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. 

{% tabs %}
{% tab title="Intel" %}
Use the project's installer for Java 1.8.0\_152 (as documented in the repo).

```bash
./setup.sh
```

{% hint style="success" %}
Intel systems can safely use the default Java 8 setup without modifications.
{% endhint %}
{% endtab %}

{% tab title="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:

```bash
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
```

{% hint style="success" %}
Apple Silicon systems generally load faster but require ARM-native Java 11 to avoid “Bad CPU type” errors.
{% endhint %}
{% endtab %}
{% endtabs %}

#### Step 3 — Install pyenv

```bash
brew update
brew install pyenv
```

#### Step 4 — Install Python 3.10

```bash
pyenv install 3.10
pyenv global 3.10
```

#### Step 5 — Install required Python packages

```bash
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](https://github.com/gensyn-ai/blockassist/issues).

#### Common Fixes

1. **Minecraft times out while starting**

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

```bash
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.

***

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

Install ARM64 Java 11 and set JAVA\_HOME:

```bash
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
```

***

3. **Port 10000 already in use or stuck processes**

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

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

{% hint style="info" %}
Be sure to re-run the app after clearing processes.
{% endhint %}

***

4. **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. 

```bash
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
```

***

5. **`pyenv` using the wrong Python version**

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

```bash
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
```

{% hint style="info" %}
You can also use this in the event that there are missing packages/dependencies.
{% endhint %}

***

6. **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.

***

7. **Missing system utilities**

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

```bash
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.

{% tabs %}
{% tab title="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.

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

{% endtab %}

{% tab title="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.

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

{% endtab %}
{% endtabs %}

**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.

{% hint style="success" %}
If you need additional support, you can [open a ticket](https://github.com/gensyn-ai/blockassist/issues) or [visit our Discord.](https://discord.com/invite/gensyn)
{% endhint %}