Windows (WSL 2)

Get up and running with BlockAssist on your Windows device with a WSL 2 environment.

Overview

This guide explains how to install and run BlockAssist v0.1.0 on Windows 10 or 11 using Windows Subsystem for Linux (WSL). It walks you through environment setup, dependency installation, authentication, and configuration for running the Minecraft interface through VcXsrv.

Prerequisites

• Windows 10/11 with WSL 2 enabled

• Ubuntu 22.04 LTS (recommended) or another supported Linux distribution inside WSL

• At least 12 GB RAM (32 GB recommended)

• Git installed on both Windows and WSL

• A Hugging Face account with a Write-access API token

• Gensyn Testnet account

If you don't have a Testnet account, don't worry--you'll be prompted to create it automatically on your first log-in attempt.

Dependencies

• Core: Python 3.10 (via pyenv), Java 1.8.0_152 (OpenJDK 8), Git

• Display Server: VcXsrv or another X Server for Windows

• GPU Support (Optional): CUDA and cuDNN for Nvidia GPUs

Installation Steps

Step 1 — Clone the Repository

Open your WSL terminal and clone the BlockAssist repository:

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

Then, navigate to the directory.

cd blockassist

Step 2 — Install Core Dependencies

1. Run the setup script to install Java.

./setup.sh

1. Next, install and configure your Python environment:

curl -fsSL https://pyenv.run | bash

1. Configure pyenv:

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
eval "$(pyenv virtualenv-init -)"

1. Reload your shell after configuring your Python environment using source ~/.bashrc.

2. Update your system and install build tools:

sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
curl git libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

1. Install Python 3.10 and set it globally:

pyenv install 3.10.0
pyenv global 3.10.0

1. Install Python libraries:

pip install psutil readchar rich

Step 3 — Configure Node.js and Yarn

1. Install Node Version Manager (NVM):

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

1. Load NVM and install Node LTS:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install --lts
nvm alias default 'lts/*'
nvm use default

1. Enable Corepack and install Yarn:

corepack enable
corepack prepare yarn@stable --activate
node -v
npm -v
yarn -v

Step 4 — Optional GPU Setup (cuDNN)

If you have an Nvidia GPU, install cuDNN for acceleration.

Use the appropriate installer for Ubuntu 22.04, then run:

sudo apt update
sudo apt install -y libcudnn9 libcudnn9-dev
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

Step 5 — Verify Installation

You're now ready to create and activate a virtual environment:

python3 -m venv blockassist-venv
source blockassist-venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install -e .

Confirm Malmo is detected:

python - <<'PY'
import pkgutil
print('malmo' in [m.name for m in pkgutil.iter_modules()])
PY

---

Platform-Specific Notes

When launching VcXsrv on Windows, make sure you've enabled/disabled the following:

Enable	Disable
Multi-Window	Access Control
Start no client	Native OpenGL

Also, make sure to:

• Set the display variable in WSL 2: export DISPLAY=<WINDOWS_IP>:0

• Test X11 forwarding with xeyes

If you see black screens or OpenGL crashes, enable software rendering:

export LIBGL_ALWAYS_SOFTWARE=1
export MESA_LOADER_DRIVER_OVERRIDE=llvmpipe
export LIBGL_ALWAYS_INDIRECT=1
export _JAVA_OPTIONS='-Xms512m -Xmx2g -Dorg.lwjgl.opengl.Display.allowSoftwareOpenGL=true'

Authentication

1

Navigate to the Directory

Enter cd modal-login and run yarn install followed by yarn dev.

2

Go to LocalHost

Open a browser and go to http://localhost:3000, log in to your Gensyn Testnet account, and then stop the server with Ctrl+C.

3

Activate your Environment

Return to the main directory and run source blockassist-venv/bin/activate.

4

Start BlockAssist

To start BlockAssist, enter python3 run.py.

When prompted, enter your HuggingFace token.

Troubleshooting

Here's a list of some common problems and quick fixes.

Issue	Solution
Minecraft window not opening	Check DISPLAY variable and VcXsrv configuration
Black screen or OpenGL crash	Enable software rendering
“pyenv: command not found”	Reinitialize pyenv and reload shell
“malmo.log not found”	Reinstall using pip install -e .
Startup freezes at 100%	Wait for about one minute, then press ENTER
“Minecraft unexpectedly crashed on launch”	Edit scripts/run_malmo.sh to include --timeout 300

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