Running BlockAssist on a Remote Linux Desktop

Learn how to run BlockAssist on a remote Linux environment using several types of devices.

Note: this path is highly experimental and not officially supported. Feel free to adapt the steps and share any issues or improvements you discover.

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.

Note the droplet’s public IP, which you will use for SSH, VNC, and Moonlight.

Step 2 — First-time Desktop Access

1. SSH to the droplet as root:

ssh root@<DROPLET_IP>

1. The first-login banner shows a random VNC password. Copy it.

2. Give the pre-installed gui user sudo rights:

sudo usermod -aG sudo gui
sudo reboot

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

You run these commands once. To record more episodes later, read this guide on running & training models with BlockAssist.

1. In the VNC desktop, open Terminal and install the build tools:

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

1. Clone BlockAssist:

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.

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

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:

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

1. Open its web UI (http://localhost:47990) in the VNC browser and set an admin password.

2. Allow GameStream ports:

sudo ufw allow 47984/tcp 47989/tcp 48010/tcp
sudo ufw allow 47998:48002/udp 47990/tcp

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

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.

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