Beadbox en Windows + WSL2

Si tu proyecto vive en WSL2 — en cualquier ruta bajo \\wsl.localhost\ o \\wsl$\ — instala Beadbox para Linux dentro de WSL y lánzalo mediante WSLg. El .exe nativo de Windows no está soportado contra rutas de WSL2. Esta guía está dirigida a Ubuntu 24.04 LTS; 22.04 no está soportado (consulta Requisitos previos).

Por qué Beadbox para Linux en WSL

Cuando tu workspace vive en una ruta como \\wsl.localhost\Ubuntu\home\you\my-project, Beadbox.exe ejecutándose en Windows tiene que cruzar el puente del sistema de archivos 9P en cada invocación del CLI bd. El CLI bd arranca un runtime de Go y reinicializa el almacén Dolt embebido en cada llamada, y el kernel de Linux dentro de WSL2 aplica una semántica de flock() que el lado de Windows no puede respetar de forma fiable.

El resultado son dos modos de fallo: llamadas en caliente medidas en torno a 1240 ms (muy por encima del margen de 500 ms del polling de Beadbox) y errores intermitentes de flock cuando dos procesos tocan el workspace a la vez. La respuesta más limpia es ejecutar Beadbox donde ya vive el workspace — dentro de WSL2 — y dejar que WSLg renderice la GUI en Windows.

Requisitos previos

Esta guía está dirigida a Ubuntu 24.04 LTS dentro de WSL2. Ubuntu 22.04 no funcionará — el .deb de Beadbox depende de libwebkit2gtk-4.1, que solo viene de forma nativa en 24.04 y posteriores. Las distros de WSL2 más antiguas fallarán en el paso de instalación con un error de dependencias no satisfechas.

Dos requisitos previos antes del Paso 1:

  1. Usa WSL2 por defecto, no WSL1. WSLg solo renderiza apps GUI en WSL2. Ejecuta esto una vez en PowerShell antes de instalar la distro:

    wsl --set-default-version 2

  2. Instala Ubuntu 24.04 (o actualiza una distro existente). Este paso es interactivo — la descarga de la imagen tarda unos minutos y, al terminar, se te pedirá crear un usuario y una contraseña de Linux:

    wsl --install Ubuntu-24.04

  3. Verifica que la distro está en WSL2:

    wsl --list --verbose

La salida debe mostrar VERSION 2 junto a Ubuntu-24.04. Si muestra 1, conviértela: wsl --set-version Ubuntu-24.04 2.

Instalar Beadbox para Linux en WSL2

Estos comandos se ejecutan dentro de tu terminal de Ubuntu 24.04 en WSL2. Abre una con wsl -d Ubuntu-24.04 desde PowerShell, o elige la distro desde el desplegable de Windows Terminal.

1. Instalar el CLI beads

Beadbox envuelve el CLI bd, así que necesitas ambos. Instala bd primero:

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

Verifica con bd --version. Deberías ver la cadena de versión de bd.

2. Descargar el .deb de Beadbox

Obtén el último .deb para Linux desde las releases de GitHub:

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. Instalar el .deb

Refresca primero el índice de apt — las distros recién instaladas de WSL2 traen una lista de paquetes desactualizada y, de lo contrario, la instalación fallará con errores 404 en dependencias transitivas. Después instala el .deb en la misma línea:

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

Si apt sigue reportando dependencias faltantes después del refresco, ejecuta sudo apt --fix-broken install e inténtalo de nuevo.

Lanzar mediante WSLg

WSLg viene con WSL2 en Windows 10 y 11, y renderiza apps GUI de Linux directamente en tu escritorio de Windows. Sin configurar X server, sin configuración extra — solo ejecuta la app:

beadbox

El primer arranque puede tardar unos segundos mientras WSLg negocia el display. Después de eso, Beadbox se comporta como cualquier otra ventana nativa: ánclala a tu barra de tareas, alterna con alt-tab, arrástrala entre monitores. Cuando abras un workspace, apúntalo a la ruta del lado Linux (~/my-project), no a la ruta del lado Windows. Dentro de WSL, ~/ es el home correcto.

Consejo: si quieres un acceso directo en el menú Inicio, el .deb instala una entrada .desktop que Windows expone automáticamente como "Beadbox (Ubuntu)" o similar. Búscalo en el menú Inicio tras la instalación.

¿Ya te topaste con el error de flock?

Si instalaste Beadbox.exe e intentaste abrir un workspace de WSL, probablemente viste un error que mencionaba flock, un fallo del modo embebido o que el workspace no cargaba. La solución es directa:

  1. Cierra el workspace en Beadbox.exe (o cierra la app por completo). El build nativo de Windows no funcionará contra este workspace.
  2. Sigue los pasos de instalación de arriba dentro de tu distro de WSL2 para instalar Beadbox para Linux.
  3. Abre Beadbox desde dentro de WSL (ejecuta beadbox en la terminal de WSL) y abre el workspace usando su ruta de Linux (~/my-project).

Puedes mantener Beadbox.exe instalado para proyectos alojados en el lado de Windows (rutas como C:\Users\you\my-project). El build de Windows funciona bien para esos — solo los proyectos alojados en WSL necesitan el build de Linux.

Solución de problemas

Avisos de libEGL / Mesa al iniciar

Cuando ejecutes beadbox por primera vez, la terminal puede mostrar avisos de libEGL, Mesa o de los drivers GL sobre la falta de aceleración por hardware o el fallback al renderizado por software. Esto es normal en WSLg — WSL2 no expone tu GPU de Windows directamente al lado Linux, así que el stack de la GUI cae a rutas por software. La app arranca sin problemas y corre a la velocidad habitual de Beadbox; los avisos son ruido, no errores.

Contexto y referencias

Ambos builds (.exe de Windows y .deb de Linux) salen de la misma base de código de Beadbox. La razón por la que el .exe no puede operar contra un workspace de WSL es estructural, no un bug que planeemos arreglar — la matemática de la latencia y el puente del sistema de archivos están en su contra.

Si quieres el detalle arquitectónico tras esta decisión, los design briefs y el tracer de latencia que descartaron los caminos rechazados están enlazados abajo.