Beadbox on Windows + WSL2

Why Linux Beadbox in WSL

When your workspace lives at a path like \\wsl.localhost\Ubuntu\home\you\my-project, Beadbox.exe running on Windows has to reach across the 9P file-system bridge for every bd CLI invocation. The bd CLI bootstraps a Go runtime and re-initializes the embedded Dolt store on each call, and the Linux kernel inside WSL2 enforces flock() semantics that the Windows side cannot honour reliably.

The result is two failure modes: warm calls measured around 1240 ms (well over Beadbox's 500 ms polling envelope), and intermittent flock errors when two processes touch the workspace at once. The cleaner answer is to run Beadbox where the workspace already lives — inside WSL2 — and let WSLg render the GUI on Windows.

Prerequisites

This guide targets Ubuntu 24.04 LTS inside WSL2. Ubuntu 22.04 will not work — the Beadbox .deb depends on libwebkit2gtk-4.1, which only ships natively in 24.04 and later. Older WSL2 distros will fail at the install step with an unmet-dependency error.

Two prerequisites before Step 1:

1. Default to WSL2, not WSL1. WSLg only renders GUI apps on WSL2. Run this once in PowerShell before installing the distro:

   wsl --set-default-version 2

2. Install Ubuntu 24.04 (or upgrade an existing distro). This step is interactive — the image download takes a few minutes, and you will be prompted to create a Linux username and password when it finishes:

   wsl --install Ubuntu-24.04

3. Verify the distro is on WSL2:

   wsl --list --verbose

The output should show VERSION 2 next to Ubuntu-24.04. If it shows 1, convert it: wsl --set-version Ubuntu-24.04 2.

Install Linux Beadbox in WSL2

These commands run inside your Ubuntu 24.04 WSL2 terminal. Open one with wsl -d Ubuntu-24.04 from PowerShell, or pick the distro from the Windows Terminal dropdown.

1. Install the beads CLI

Beadbox wraps the bd CLI, so you need both. Install bd first:

curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

Verify with bd --version. You should see the bd version string.

2. Download the Beadbox .deb

GitHub release asset filenames include the version number, so this snippet resolves the latest version first, then downloads the matching .deb:

VER=$(curl -sSL https://api.github.com/repos/beadbox/beadbox/releases/latest | sed -n 's/.*"tag_name":[[:space:]]*"v\{0,1\}\([^"]*\)".*/\1/p')
curl -L -o beadbox.deb "https://github.com/beadbox/beadbox/releases/download/v${VER}/beadbox_${VER}_Linux_amd64.deb"

3. Install the .deb

Refresh the apt index first — fresh WSL2 distros ship with a stale package list and the install will fail with 404s on transitive dependencies otherwise. Then install the .deb in the same line:

sudo apt-get update && sudo apt install ./beadbox.deb

If apt still reports missing dependencies after the refresh, run sudo apt --fix-broken install and try again.

Launch via WSLg

WSLg ships with WSL2 on Windows 10 and 11 and renders Linux GUI apps directly on your Windows desktop. No X server setup, no extra config — just run the app:

beadbox

The first launch may take a few seconds while WSLg negotiates the display. After that, Beadbox behaves like any other native window: pin it to your taskbar, alt-tab to it, drag it across monitors. When you open a workspace, point it at the Linux-side path (~/my-project), not the Windows-side path. Inside WSL, ~/ is the right home.

Tip: if you want a Start-menu shortcut, the .deb installs a .desktop entry that Windows surfaces automatically as "Beadbox (Ubuntu)" or similar. Search for it in the Start menu after the install.

Already hit the flock error?

If you installed Beadbox.exe and tried to open a WSL workspace, you likely saw an error mentioning flock, embedded-mode failure, or the workspace failing to load. The fix is straightforward:

1. Close the workspace in Beadbox.exe (or quit the app entirely). The native Windows build will not work against this workspace.
2. Follow the install steps above inside your WSL2 distro to install Linux Beadbox.
3. Open Beadbox from inside WSL (run beadbox in the WSL terminal) and open the workspace using its Linux path (~/my-project).

You can keep Beadbox.exe installed for projects hosted on the Windows side (paths like C:\Users\you\my-project). The Windows build is fine for those — it is only WSL-hosted projects that need the Linux build.

Troubleshooting

libEGL / Mesa warnings on launch

When you run beadbox for the first time, the terminal may print warnings from libEGL, Mesa, or GL drivers about missing hardware acceleration or fallback to software rendering. These are normal under WSLg — WSL2 does not expose your Windows GPU directly to the Linux side, so the GUI stack falls back to software paths. The app launches fine and runs at full Beadbox speed; the warnings are noise, not errors.

Background and references

Both builds (Windows .exe and Linux .deb) ship from the same Beadbox codebase. The reason the .exe cannot drive a WSL workspace is structural, not a bug we plan to fix — the latency math and the file-system bridge are stacked against it.

If you want the architectural detail behind this decision, the design briefs and the latency tracer that ruled out the rejected paths are linked below.

• Beadbox issues on GitHub
• beads CLI repository
• Microsoft: Run Linux GUI apps with WSLg