bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 16쪽 중 10쪽
d.*
{% hint style="warning" %}
For “Out of memory” (OOM) build errors, close other applications or increase Docker memory limit (above).
{% endhint %}
#### Login and Identity Issues
If you're experiencing issues logging in, this section provides quick fixes for login modal issues, *peer identity* issues, and more.
| Issue | Fix |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *Browser window never opens for login* | <ol><li>Manually open the login URL by typing <code><http://localhost:3000></code> into your browser.</li><li>If you're using a VM/VPS, use the <code>flag -L 3000:localhost:3000</code> port forwarding flag when connecting.</li></ol> |
| *Login modal fails to load, or OTP not sent to email* | <p></p><ol><li>Upgrade <code>viem</code> to version 2.25.0 inside <code>modal-login/package.json</code>.</li><li>Run <code>cd modal-login && yarn upgrade && yarn add next\@latest viem\@latest</code>.</li></ol> |
| *Login works, but training fails after re-login* | Delete the old peer identity and restart using `sudo rm swarm.pem`. Then re-run RL Swarm and log in again with the same email. |
| *Lost `swarm.pem` identity* | You must generate a new one using the same email to retain your on-chain account. |
| *Running multiple nodes* | Use the same email login for each node. Each node has its own peer ID,but shares the same EOA. |
| *VPS login fallbacks* | If `port:3000` is blocked, you can use temporary tunnels such as Cloudflare or nGrok if comfortable with networking tools. |
### Training and Performance Issues
Some commonly experienced training issues are 'false flags' whereas others require some manual input. 
Symptom's we've seen:
* **Training appears stuck, or isn't progressing:** Consumer-grade CPUs, especially MacBooks, can take more than \~20 minutes per training cycle. Please be patient! 
{% hint style="warning" %}
If training freezes for longer than a previous iteration, use `ctrl/cmd+c` to stop, then return the container & script. 
{% endhint %}
* **"Skipped round" messages:** This is normal. It means your machine was slower than the swarm round pace. 
* **OOM (Out of Memory) errors:** Try closing other applications and increasing the Docker memory allocation as mentioned above.
* **High CPU usage and/or thermal throttling:** This is normal if you're training in CPU-only mode. If your device allows for it, try switching to GPU-only mode.
* **"GPU not detected" warnings:** Confirm that your drivers are correctly installed and recognized, and that the container is launched using `swarm-gpu`. 
{% hint style="info" %}
To force CPU-only mode explicity, use the `swarm-cpu` command.
{% endhint %}
### Network and Connectivity Issues
Docker may need to be configured in your Firewall settings to allow outbound traffic, or you may be in a region where RL Swarm is currently unavailable. 
{% hint style="danger" %}
Nodes from China, Russia, Ukraine, and sometimes Japan are blocked. Use a different region or VPS outside those areas.
{% endhint %}
Common connection issues:
* **Node doesn't appear on the dashboard:** Check your internet connection and make sure the firewall allows outbound traffic from Docker. Also, visit the [Gensyn Dashboard](https://dashboard.gensyn.ai/) and confirm that your node is visible under RL Swarm.
* **Predication Market bets are not visible:** Make sure you answered 'Y' when asked to join the Prediction Market. Rerun the script if necessary. 
* **VPS connection drops:** If the SSH tunnel breaks and you see “broken pipe” errors, press `ctrl/cmd+c` to kill the script, then restart RL Swarm, and it should cleanly re-initalize. 
### Logs and Diagnostics
Browse the table below to find the most useful log types and locations inside the `rl-swarm` repository. 
| Location | Type |
| ----------------------------------------------- | ------------------------------------------------------------------------ |
| `/logs/yarn.log` | Modal login server activity. |
| `/logs/swarm.log` | The main application log. |
| `/logs/wandb/` | Training logs and `debug.log` for Weights & Biases (if this is enabled). |
| `/logs/prg_record.txt` and `swarm_launcher.log` | Prediction Market details. |
#### How to Interpret Logs
Many warnings (e.g., Protobuf "yanked version") are **benign** and can be safely ignored.
When looking at your logs for errors, look for lines containing `ERROR`, `RuntimeError` or `Traceback` to locate actual failure points. 
{% hint style="info" %}
When posting to [Discord](https://discord.com/invite/gensyn) or [Github](https://github.com/gensyn-ai/rl-swarm/issues), please attach the relevant section of `swarm.log` as well as your system info. 
{% endhint %}
### Advanced and Recovery Scenarios
Below are some specific scenarios you may run into when running multiple nodes, or nodes on different machines.
* **Moving to a new machine:** Make sure to back up your `swarm.pen` from the repo's root, then copy it into the *same directory* on the new machine before launching RL Swarm. 
* **Running multiple GPUs or peers:** Install RL Swarm separately for each GPU, and exposre each peer under a different port.
* **Clean rebuilds:** Stop all containers and processes by using `ctrl/cmd+c` then run `docker system prune -a` to remove old containers. Delete `.venv` and re-clone the repository if necessary. 
* **Using tuneling tools in cases where the login port is blocked:** This is only for advanced users who are comfortable with network tools. Use the simplest tool that works, since the local login method is recommended for security and reliablity. Tools include **Cloudflare**, **nGrok**, or **localtunnel**.
### When to Esclate 
If you're experiencing an issue that none of the above steps are able to resolve, we're here to help. 
1. Check the [GitHub Issues](https://github.com/gensyn-ai/rl-swarm/issues) page to see if your issue has already been reported.
2. If you open a new issue or ask for help on [Discord](https://discord.com/invite/gensyn), please include the operating system and version, CPU and GPU model, amount of RAM, and as much context on the error(s) as possible. 
# BlockAssist (Paused)
BlockAssist is an interactive, AI-driven Minecraft environment where reinforcement learning agents learn from your actions.
{% hint style="info" icon="triangle-exclamation" %}
**BlockAssist has been sunset.** 
*These docs are preserved for reference but BlockAssist is no longer actively maintained.*
Alternatively, you can explore [Delphi](https://app.delphi.fyi/), a set of tools for creating information markets.
{% endhint %}
### What is BlockAssist?
BlockAssist is an AI assistant that learns from its user’s actions in Minecraft. The assistant appears in-game with you, starting with only basic knowledge of the game’s commands. 
As you play, it learns how to assist you in building, learning directly from your actions. BlockAssist bridges Gensyn’s research in decentralized machine learning with a game-based interface that’s easy to explore and extend.
<figure><img src="https://1034405018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIcazOdplbOmP4R0T7sG8%2Fuploads%2FTeR2MiFcXefPmXwmEhD0%2Fblockassist_tui_starting_from_terminal_tui_demo.png?alt=media&token=54b06d48-cddd-40f9-ab59-b5ca566460f1" alt=""><figcaption></figcaption></figure>
### Why It Exists
Modern machine learning systems rely on centralized *compute clusters* that limit participation and experimentation. 
BlockAssist was created to demonstrate how learning can happen collaboratively and trustlessly across many smaller nodes, which is the same principle that underpins the Gensyn network. 
By turning reinforcement learning into a playable experiment, BlockAssist helps researchers, developers, and enthusiasts visualize what decentralized AI coordination looks like in action.
{% hint style="success" %}
BlockAssist is part of Gensyn’s effort to build the network for machine intelligence. 
It offers a lightweight, playable example of the coordination and verification layers seen in Gensyn’s research, like RL Swarm for collaborative RL, Verde for verification, CheckFree for fault tolerance, and NoLoCo for efficient communication.
{% endhint %}
#### What You Can Do With It
Users can clone the repo, run it locally, and play a guided Minecraft scenario where they're tasked with building a structure. 
As you play, an AI bot observes your actions—learning how to build alongside you by watching **\[1]** what you do, **\[2]** where you place blocks, and **\[3]** how you solve the task. 
After each session (called an “episode”), BlockAssist trains a machine learning model on your gameplay data, right on your machine. Once training is complete, users upload their personalized model to Hugging Face using their token.
This submission is then recorded on the Gensyn Testnet, contributing to a *decentralized, verifiable record of your participation* and model training. 
{% hint style="info" %}
BlockAssist’s purpose is to demonstrate “assistance learning”, where AI that learns directly from human actions, not just static datasets while giving users a hands-on way to contribute to and experiment with decentralized AI training.
{% endhint %}
# Getting Started
Get up and running with BlockAssist and start training your own model.
{% embed url="<https://github.com/gensyn-ai/blockassist>" %}
{% hint style="warning" %}
BlockAssist has been sunset. Please see the [home page](/testnet/blockassist) for more information.
{% endhint %}
## Overview
This page helps you prepare your system and choose the correct installation path for BlockAssist. It provides a readiness checklist, supported platforms, and an overview of the setup process before you begin installing and running BlockAssist on your device.
#### Before You Begin
BlockAssist is available across several environments: [Windows (via WSL 2)](/testnet/blockassist/getting-started/windows-wsl-2), [Linux (Ubuntu 22.04+)](/testnet/blockassist/getting-started/linux), [macOS (Intel and Apple Silicon)](/testnet/blockassist/getting-started/macos), and [remote Linux desktops.](/testnet/blockassist/getting-started/linux/running-blockassist-on-a-remote-linux-desktop)
Before you start, make sure you meet the basic requirements and have the necessary accounts.
### System Requirements
* 12 GB RAM minimum (32 GB recommended)
* Stable internet connection
* At least 10 GB of available storage (for overhead)
* Modern multi-core CPU (Intel, AMD, or Apple Silicon)
#### Accounts & Access
* **Hugging Face account:** You’ll need a Write-access API token to upload your model after training. See the Hugging Face Guide for instructions.
* **Gensyn Testnet account:** Automatically created when you first log in through your browser during setup.
#### Software Requirements (All Platforms)
* Python 3.10.x
* Java 1.8.0\_152 (OpenJDK 8)
* Git
* Internet access for dependency installation and authentication
### Supported Platforms & Installation Paths
BlockAssist runs on multiple environments. Choose the guide that matches your operating system or setup.
<table data-view="cards"><thead><tr><th align="center"></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><a href="/testnet/blockassist/getting-started/windows-wsl-2">Windows (WSL 2)</a></td><td>Run BlockAssist on Windows 10 or 11 using Windows Subsystem for Linux 2 (WSL). This setup requires an X Server such as VcXsrv to render the Minecraft environment.</td><td></td><td><a href="/testnet/blockassist/getting-started/windows-wsl-2">Windows (WSL 2)</a></td></tr><tr><td align="center"><a href="/testnet/blockassist/getting-started/linux">Linux (Ubuntu 22.04+)</a></td><td>Install BlockAssist natively on Ubuntu or a compatible distribution for the most stable experience.</td><td></td><td><a href="/testnet/blockassist/getting-started/linux">Linux</a></td></tr><tr><td align="center"><a href="/testnet/blockassist/getting-started/macos">macOS (Intel & Apple Silicon)</a></td><td>Install and run BlockAssist on macOS using Homebrew for dependency management. Both Intel and M-series processors are supported.</td><td></td><td><a href="/testnet/blockassist/getting-started/macos">macOS</a></td></tr></tbody></table>
{% hint style="success" %}
All platform installations share a few core dependencies. These are handled within each platform’s guide, but if you encounter dependency issues, consult your specific platform’s **Troubleshooting** section.
{% endhint %}
### Installation Flow
Every installation follows the same general flow, regardless of platform.
1. Choose and complete the correct installation guide for your platform.
2. Run BlockAssist from your terminal.
3. Log in when prompted:
* Paste your Hugging Face Write-access token.
* Authenticate through the Gensyn Testnet browser window.
4. Play and record your in-game building session.
5. Wait for the model to train and upload automatically to Hugging Face and the Gensyn Testnet.
{% hint style="info" %}
This sequence is similar on all platforms, with commands and dependencies varying by operating system.
{% endhint %}
***
#### Cursor Setup (Optional)
For users who prefer a more guided setup experience, [BlockAssist can also be configured through Cursor AI](/testnet/blockassist/using-blockassist/running-blockassist-with-cursor), an intelligent code editor that walks you through installation steps interactively. This method is platform-agnostic but still requires that dependencies and environment setup steps are completed.
#### Additional Resources
After you've successfully installed BlockAssist on your system, continue with: 
* [Running BlockAssist](/testnet/blockassist/using-blockassist): Instructions for launching and training.
* [Hugging Face Guide](/testnet/blockassist/hugging-face-guide): Generate and manage your API token for uploads.
# 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](/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 (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:
```bash
git clone https://github.com/gensyn-ai/blockassist.git
```
Then, navigate to the directory.
```bash
cd blockassist
```
#### Step 2 — Install Core Dependencies
1. Run the setup script to install Java.
```bash
./setup.sh
```
2. Next, install and configure your Python environment:
```bash
curl -fsSL https://pyenv.run | bash
```
3. Configure `pyenv`:
```bash
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
eval "$(pyenv virtualenv-init -)"
```
4. Reload your shell after configuring your Python environment using `source ~/.bashrc`.
5. Update your system and install build tools:
```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
```
6. Install Python 3.10 and set it globally:
```bash
pyenv install 3.10.0
pyenv global 3.10.0
```
7. Install Python libraries: 
```
pip install psutil readchar rich
```
#### Step 3 — Configure Node.js and Yarn
1. Install Node Version Manager (NVM):
```bash
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
```
2. Load NVM and install Node LTS:
```bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install --lts
nvm alias default 'lts/*'
nvm use default
```
3. Enable Corepack and install Yarn:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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
{% stepper %}
{% step %}
### Navigate to the Directory
Enter `cd modal-login` and run `yarn install` followed by `yarn dev`.
{% endstep %}
{% step %}
### 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.
{% endstep %}
{% step %}
### Activate your Environment
Return to the main directory and run `source blockassist-venv/bin/activate`.
{% endstep %}
{% step %}
### Start BlockAssist
To start BlockAssist, enter `python3 run.py`.
{% hint style="warning" %}
When prompted, enter your HuggingFace token. 
{% endhint %}
{% endstep %}
{% endstepper %}
### 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` |
{% hint style="success" %}
If you need additional support, you can [open a ticket](https://github프로젝트로 돌아가기
