# Linux

## 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](/testnet/blockassist/hugging-face-guide.md)
* Gensyn Testnet account

{% hint style="success" %}
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.
{% endhint %}

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

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

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

Verify Java installation by running:

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

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

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

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

```bash
pyenv install 3.10.13  
pyenv global 3.10.13
```

Confirm that Python was installed correctly using the following command: 

```bash
python --version
```

#### Step 5 — Install Python Packages

Install required Python libraries for BlockAssist.

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

```bash
java -version  
python --version  
pyenv versions
```

{% hint style="info" %}
Each should return a valid version number with no errors.
{% endhint %}

***

### 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](/testnet/blockassist/hugging-face-guide.md) 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:

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

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

{% 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gensyn.ai/testnet/blockassist/getting-started/linux.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.