Linux

Get up and running with BlockAssist in your Ubuntu 22.04+ Linux environment.

Overview

Use this guide to install and set up BlockAssist on Linux systems, with Ubuntu 22.04 LTS as the recommended distribution. It includes environment configuration, dependency installation, and verification steps to prepare for running and training BlockAssist locally.

Prerequisites

• Ubuntu 22.04 LTS or compatible Linux distribution

• At least 12 GB RAM (32 GB recommended for training stability)

• Git installed

• 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.x (via pyenv) & Java 1.8.0_152 (OpenJDK 8)

• Optional: CUDA/cuDNN for Nvidia GPU acceleration

• Package Manager: APT (default for Ubuntu)

Installation Steps

Step 1 — Clone the Repository

Clone the BlockAssist repository and navigate into it.

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

Step 2 — Install Java 1.8.0_152

Run the setup script included with the repository. This installs and configures Java 8, which is required for the underlying Minecraft environment.

./setup.sh

Verify Java installation by running:

java -version

You should see a version number beginning with 1.8.0_152.

Step 3 — Install pyenv

Install pyenv to manage your Python environment.

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

Follow the instructions provided by pyenv to add it to your shell configuration file (for example, .bashrc or .zshrc).

Then initialize pyenv:

export PYENV_ROOT="$HOME/.pyenv"  
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"  
eval "$(pyenv init --path)"  
eval "$(pyenv init -)"  
source ~/.bashrc

Step 4 — Install Core Dependencies

Install system-level dependencies required for building and compiling Python.

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 zip unzip

Once complete, use pyenv to install Python 3.10 and set it globally.

pyenv install 3.10.13  
pyenv global 3.10.13

Confirm that Python was installed correctly using the following command:

python --version

Step 5 — Install Python Packages

Install required Python libraries for BlockAssist.

pip install psutil readchar rich

Step 6 — Verify Installation

At this point, your environment is ready. Verify that Java, Python, and pyenv are properly configured:

java -version  
python --version  
pyenv versions

Each should return a valid version number with no errors.

---

Platform-Specific Notes

• Use Ubuntu 22.04 LTS for maximum compatibility. Other distributions may require slight package name adjustments.

• If you are running Ubuntu on ARM hardware (such as Raspberry Pi or ARM-based servers), ensure that you install the ARM-compatible version of OpenJDK 8.

• For Nvidia GPU users, installing CUDA and cuDNN is optional but can accelerate model training.

Authentication

Once installation is complete, you will authenticate when running BlockAssist for the first time.

• You’ll be prompted for your Hugging Face Write-access API token. Follow the instructions provided in the Hugging Face Guide to generate one if you haven’t already.

• A browser window will open for Gensyn Testnet login. If you have logged in previously, this step will be skipped automatically.

Troubleshooting

Below are some quick fixes for some common installation issues.

• If pyenv: command not found, reinitialize pyenv using the following command:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

• If Java fails to install via setup.sh, manually install OpenJDK 8:

sudo apt install -y openjdk-8-jdk

• If Python installation fails, ensure all required build dependencies are installed (build-essential, zlib1g-dev, libssl-dev, etc.).

For any missing Python packages, rerun pip install -e . from inside the BlockAssist folder.

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