Beadbox unter Windows + WSL2

Warum Linux-Beadbox in WSL

Wenn Ihr Workspace unter einem Pfad wie \\wsl.localhost\Ubuntu\home\you\my-project liegt, muss Beadbox.exe unter Windows bei jedem bd-CLI-Aufruf über die 9P-Dateisystem-Brücke greifen. Das bd CLI startet bei jedem Aufruf eine Go-Runtime und initialisiert den eingebetteten Dolt-Speicher neu, und der Linux-Kernel innerhalb von WSL2 erzwingt flock()-Semantiken, die die Windows-Seite nicht zuverlässig einhalten kann.

Das Ergebnis sind zwei Fehlermodi: Warm-Aufrufe um die 1240 ms (deutlich über dem 500-ms-Polling-Fenster von Beadbox) und sporadische flock-Fehler, wenn zwei Prozesse den Workspace gleichzeitig anfassen. Die sauberere Antwort ist, Beadbox dort laufen zu lassen, wo der Workspace bereits liegt — innerhalb von WSL2 — und WSLg die GUI auf Windows rendern zu lassen.

Voraussetzungen

Diese Anleitung zielt auf Ubuntu 24.04 LTS innerhalb von WSL2. Ubuntu 22.04 wird nicht funktionieren — das Beadbox-.deb hängt von libwebkit2gtk-4.1 ab, das nativ erst ab 24.04 ausgeliefert wird. Ältere WSL2-Distributionen scheitern beim Installationsschritt mit einem Fehler über nicht erfüllte Abhängigkeiten.

Zwei Voraussetzungen vor Schritt 1:

1. Standard auf WSL2 setzen, nicht WSL1. WSLg rendert GUI-Apps nur unter WSL2. Führen Sie dies einmal in PowerShell aus, bevor Sie die Distribution installieren:

   wsl --set-default-version 2

2. Ubuntu 24.04 installieren (oder eine bestehende Distribution upgraden). Dieser Schritt ist interaktiv — der Image-Download dauert einige Minuten, und am Ende werden Sie aufgefordert, einen Linux-Benutzernamen und ein Passwort anzulegen:

   wsl --install Ubuntu-24.04

3. Prüfen Sie, dass die Distribution auf WSL2 läuft:

   wsl --list --verbose

Die Ausgabe sollte VERSION 2 neben Ubuntu-24.04 anzeigen. Steht dort 1, konvertieren Sie sie: wsl --set-version Ubuntu-24.04 2.

Linux-Beadbox in WSL2 installieren

Diese Befehle laufen im Terminal Ihrer Ubuntu 24.04-WSL2-Distribution. Öffnen Sie eines mit wsl -d Ubuntu-24.04 aus PowerShell oder wählen Sie die Distribution aus dem Dropdown des Windows Terminal.

1. beads CLI installieren

Beadbox umschließt das bd-CLI, daher brauchen Sie beides. Installieren Sie zuerst bd:

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

Prüfen Sie mit bd --version. Sie sollten den bd-Versions-String sehen.

2. Beadbox-.deb herunterladen

Holen Sie sich das aktuelle Linux-.deb von den GitHub-Releases:

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. Das .deb installieren

Aktualisieren Sie zuerst den apt-Index — frische WSL2-Distributionen kommen mit einer veralteten Paketliste, sonst schlägt die Installation mit 404-Fehlern bei transitiven Abhängigkeiten fehl. Dann installieren Sie das .deb in derselben Zeile:

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

Falls apt nach der Aktualisierung weiterhin fehlende Abhängigkeiten meldet, führen Sie sudo apt --fix-broken install aus und versuchen Sie es erneut.

Über WSLg starten

WSLg ist bei WSL2 unter Windows 10 und 11 dabei und rendert Linux-GUI-Apps direkt auf Ihrem Windows-Desktop. Kein X server-Setup, keine zusätzliche Konfiguration — einfach die App starten:

beadbox

Der erste Start kann einige Sekunden dauern, während WSLg das Display aushandelt. Danach verhält sich Beadbox wie jedes andere native Fenster: an die Taskleiste anheften, per Alt-Tab dorthin wechseln, über Monitore ziehen. Wenn Sie einen Workspace öffnen, zeigen Sie auf den Linux-seitigen Pfad (~/my-project), nicht auf den Windows-seitigen. Innerhalb von WSL ist ~/ das richtige Home.

Tipp: Wenn Sie eine Startmenü-Verknüpfung möchten, installiert das .deb einen .desktop-Eintrag, den Windows automatisch als "Beadbox (Ubuntu)" oder ähnlich anzeigt. Suchen Sie nach der Installation im Startmenü danach.

Schon den flock-Fehler bekommen?

Wenn Sie Beadbox.exe installiert und versucht haben, einen WSL-Workspace zu öffnen, haben Sie wahrscheinlich einen Fehler mit flock, einem Embedded-Mode-Fehlschlag oder einem nicht ladenden Workspace gesehen. Die Lösung ist einfach:

1. Schließen Sie den Workspace in Beadbox.exe (oder beenden Sie die App ganz). Der native Windows-Build wird mit diesem Workspace nicht funktionieren.
2. Folgen Sie den Installationsschritten oben in Ihrer WSL2-Distribution, um Linux-Beadbox zu installieren.
3. Öffnen Sie Beadbox aus WSL heraus (führen Sie beadbox im WSL-Terminal aus) und öffnen Sie den Workspace mit seinem Linux-Pfad (~/my-project).

Sie können Beadbox.exe für Projekte auf der Windows-Seite (Pfade wie C:\Users\you\my-project) installiert lassen. Der Windows-Build ist dafür in Ordnung — nur WSL-gehostete Projekte brauchen den Linux-Build.

Fehlerbehebung

libEGL- / Mesa-Warnungen beim Start

Wenn Sie beadbox zum ersten Mal starten, gibt das Terminal möglicherweise Warnungen von libEGL, Mesa oder GL-Treibern aus, die fehlende Hardwarebeschleunigung oder einen Rückfall auf Software-Rendering melden. Unter WSLg ist das normal — WSL2 reicht Ihre Windows-GPU nicht direkt an die Linux-Seite durch, sodass der GUI-Stack auf Software-Pfade zurückfällt. Die App startet einwandfrei und läuft mit voller Beadbox-Geschwindigkeit; die Warnungen sind Rauschen, keine Fehler.

Hintergrund und Referenzen

Beide Builds (Windows-.exe und Linux-.deb) kommen aus derselben Beadbox-Codebasis. Der Grund, warum die .exe einen WSL-Workspace nicht bedienen kann, ist strukturell, kein Bug, den wir zu beheben planen — die Latenz-Mathematik und die Dateisystem-Brücke sprechen dagegen.

Wenn Sie das architektonische Detail hinter dieser Entscheidung möchten, sind die Design-Briefs und der Latenz-Tracer, der die verworfenen Wege ausgeschlossen hat, unten verlinkt.

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