bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 16쪽 중 11쪽
.com/gensyn-ai/blockassist/issues) or [visit our Discord.](https://discord.com/invite/gensyn) 
{% endhint %}
# 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](/testnet/blockassist/hugging-face-guide)
* 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) 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 %}
# Running BlockAssist on a Remote Linux Desktop
Learn how to run BlockAssist on a remote Linux environment using several types of devices.
{% hint style="danger" %}
**Note**: this path is highly experimental and not officially supported. Feel free to adapt the steps and share any issues or improvements you discover.
{% endhint %}
## Overview
This guide shows non-technical users how to set up and run BlockAssist on a remote Ubuntu Desktop droplet at DigitalOcean and stream it with Moonlight to any laptop, phone, tablet, or TV.
### Installation & Setup Steps
#### Step 1 — Creating your Droplet
1. Sign in to DigitalOcean and click Create → Droplet.
2. Under Marketplace, choose Ubuntu Desktop (GNOME) 22.04 LTS.
| System Specifications | CPU | RAM |
| --------------------- | --- | ----- |
| Minimum | 4 | 16 GB |
| Recommended | 8 | 32 GB |
Add your SSH key, pick the nearest region, and click **Create Droplet.**
{% hint style="info" %}
Note the droplet’s public IP, which you will use for SSH, VNC, and Moonlight.
{% endhint %}
#### Step 2 — First-time Desktop Access
1. SSH to the droplet as root:
```sh
ssh root@<DROPLET_IP>
```
2. The first-login banner shows a random **VNC password**. Copy it.
3. Give the pre-installed **gui** user `sudo` rights:
```sh
sudo usermod -aG sudo gui
sudo reboot
```
4. Open any VNC client and connect to `<DROPLET_IP>:5901` using the password from Step 1. You will only need VNC again if Sunshine stops working.
#### Step 3 — Installing Dependencies
{% hint style="info" %}
You run these commands once. To record more episodes later, read [this guide on running & training models with BlockAssist.](/testnet/blockassist/using-blockassist)
{% endhint %}
1. In the VNC desktop, open **Terminal** and install the build tools:
```sh
sudo apt update
sudo apt install -y make build-essential gcc \
libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
libsqlite3-dev libncursesw5-dev xz-utils tk-dev \
libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev curl git
```
2. Clone BlockAssist:
```sh
git clone https://github.com/gensyn-ai/blockassist.git ~/blockassist
cd ~/blockassist
```
**Python & Node** 
Let `pyenv` and `nvm` read the exact versions pinned in the repository. 
```shell
# install pyenv
curl https://pyenv.run | bash
exec $SHELL
pyenv install $(cat .python-version)
pyenv global $(cat .python-version)
# install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
exec $SHELL
nvm install $(cat .nvmrc)
```
**Project Packages**
Install the required project packages using the commands below. 
```sh
pip install --upgrade pip
pip install -r requirements.txt readchar
corepack enable # enables Yarn
yarn install --frozen-lockfile
```
#### Step 3 — Streaming with Sunshine & Moonlight
1. Install Sunshine using the following command:
```sh
wget -O sunshine.deb \
https://github.com/LizardByte/Sunshine/releases/download/v0.23.1/sunshine-ubuntu-22.04-amd64.deb
sudo apt install ./sunshine.deb
systemctl --user enable --now sunshine
```
2. Open its web UI (`http://localhost:47990`) in the VNC browser and set an admin password.
3. Allow GameStream ports:
```sh
sudo ufw allow 47984/tcp 47989/tcp 48010/tcp
sudo ufw allow 47998:48002/udp 47990/tcp
```
4. On your local device install **Moonlight**, add the droplet’s IP, enter the PIN shown, and pair.\
You can now close the VNC client and use Moonlight for the rest of this guide.
#### Step 5 — Running BlockAssist
Click here for a detailed, [platform-agnostic guide on running BlockAssist.](/testnet/blockassist/using-blockassist) 
## Troubleshooting
Below are some common issues and quick fixes.
| Issue | Solution |
| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Error while installing packages | In the Chat panel press `cmd + L`, then type **Help me fix this error** and add Terminal context. |
| BlockAssist launches but will not run | In Chat type `Look at my logs folder` **…** and follow the suggestions. |
| Mouse will not turn or view is stuck | Make sure you are playing through **Moonlight**, not VNC. |
| Mission times out while loading | Upgrade the droplet to at least 8 vCPU / 32 GB RAM. |
{% 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 %}
# 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
{% 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 %}
# Using BlockAssist
Use the platform-agnostic guide below to launch BlockAssist after installation, complete tasks, train your models, and upload them via Hugging Face.
## Overview
Use the step-by-step guide below to run BlockAssist, train models, and start contributing to Gensyn's Testnet.
### Logs
Use `tail -f logs/[specific log].log` to monitor progress, and `ls logs` to see options. 
{% hint style="info" %}
You might need to press ENTER a few times when prompted.
{% endhint %}
### Running with Python
The program will install various dependencies as required. Follow any instructions and approve all asks.
{% tabs %}
{% tab title="Windows (WSL 2)" %}
Use the following command to run the script on your Windows device:
```bash
python run.py
```
{% hint style="info" %}
You can optionally prefix it with `pyenv exec` if you’re using `pyenv` to manage your Python version.
{% endhint %}
{% endtab %}
{% tab title="Linux" %}
Use the following command to run the script on your Linux device/environment:
```bash
python run.py
```
{% hint style="info" %}
You can optionally prefix it with `pyenv exec` if you’re using `pyenv` to manage your Python version.
{% endhint %}
{% endtab %}
{% tab title="macOS" %}
Use the following command to run the script on your macOS device:
```bash
pyenv exec python run.py
```
{% endtab %}
{% endtabs %}
<figure><img src="https://1034405018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIcazOdplbOmP4R0T7sG8%2Fuploads%2FOJCdrIAA9FdD2ptnfQMr%2Finitial_run_command.gif?alt=media&token=a745e4f4-abf9-4b99-81b1-3ab6a412363e" alt=""><figcaption></figcaption></figure>
#### HuggingFace Token
You will be asked to enter a [Hugging Face](https://huggingface.co) API token. 
Follow the instructions [in this guide](#huggingface-token), and make sure the token has **Write** access.
<figure><img src="https://1034405018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIcazOdplbOmP4R0T7sG8%2Fuploads%2FlaeONOrcdo6eGipNuV3C%2Fhf_token_set.png?alt=media&token=e251d075-51f0-47f0-b763-972af179cb3c" alt=""><figcaption></figcaption></figure>
#### Logging into Gensyn Testnet
The terminal will show a **LOGIN** section where the system:
* Requests accessibility permissions (approve these if prompted)
* Waits for user authentication data to be created
* Confirms successful login setup
<figure><img src="https://1034405018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIcazOdplbOmP4R0T7sG8%2Fuploads%2F0ymt6a4R7mSqCnMV2D86%2FScreenshot%202025-08-04%20at%202.13.39%E2%80%AFPM.png?alt=media&token=8프로젝트로 돌아가기
