Beadbox no Windows + WSL2

Se seu projeto está no WSL2 — em qualquer caminho sob \\wsl.localhost\ ou \\wsl$\ — instale o Beadbox para Linux dentro do WSL e rode-o via WSLg. O .exe nativo para Windows não tem suporte para caminhos do WSL2. Este guia tem como alvo o Ubuntu 24.04 LTS; o 22.04 não é suportado (veja Pré-requisitos).

Por que o Beadbox para Linux no WSL

Quando seu workspace está em um caminho como \\wsl.localhost\Ubuntu\home\voce\meu-projeto, o Beadbox.exe rodando no Windows precisa atravessar a ponte de sistema de arquivos 9P em cada chamada do CLI bd. O bd CLI inicializa um runtime Go e re-inicializa o store Dolt embutido a cada invocação, e o kernel Linux dentro do WSL2 impõe a semântica de flock() que o lado Windows não consegue honrar com confiabilidade.

O resultado são dois modos de falha: chamadas a quente medidas em torno de 1240 ms (bem acima do envelope de polling de 500 ms do Beadbox) e erros intermitentes de flock quando dois processos tocam o workspace ao mesmo tempo. A resposta mais limpa é rodar o Beadbox onde o workspace já vive — dentro do WSL2 — e deixar o WSLg renderizar a GUI no Windows.

Pré-requisitos

Este guia tem como alvo o Ubuntu 24.04 LTS dentro do WSL2. O Ubuntu 22.04 não vai funcionar — o .deb do Beadbox depende do libwebkit2gtk-4.1, que só vem nativamente no 24.04 e versões posteriores. Distros WSL2 mais antigas vão falhar na etapa de instalação com um erro de dependência não satisfeita.

Dois pré-requisitos antes do Passo 1:

  1. Use o WSL2 como padrão, não o WSL1. O WSLg só renderiza apps GUI no WSL2. Rode isto uma vez no PowerShell antes de instalar a distro:

    wsl --set-default-version 2

  2. Instale o Ubuntu 24.04 (ou atualize uma distro existente). Esta etapa é interativa — o download da imagem leva alguns minutos, e você será solicitado a criar um nome de usuário e senha do Linux quando terminar:

    wsl --install Ubuntu-24.04

  3. Verifique se a distro está no WSL2:

    wsl --list --verbose

A saída deve mostrar VERSION 2 ao lado de Ubuntu-24.04. Se mostrar 1, converta com: wsl --set-version Ubuntu-24.04 2.

Instalar o Beadbox para Linux no WSL2

Esses comandos rodam dentro do seu terminal WSL2 com Ubuntu 24.04. Abra um com wsl -d Ubuntu-24.04 no PowerShell, ou escolha a distro no menu suspenso do Windows Terminal.

1. Instale o beads CLI

O Beadbox envolve o CLI bd, então você precisa dos dois. Instale o bd primeiro:

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

Verifique com bd --version. Você deve ver a string da versão do bd.

2. Baixe o .deb do Beadbox

Pegue o .deb mais recente para Linux nas releases do 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. Instale o .deb

Atualize primeiro o índice do apt — distros WSL2 recém-criadas vêm com uma lista de pacotes desatualizada e a instalação falhará com erros 404 em dependências transitivas. Em seguida, instale o .deb na mesma linha:

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

Se o apt ainda reportar dependências faltantes após a atualização, rode sudo apt --fix-broken install e tente de novo.

Rodar via WSLg

O WSLg vem com o WSL2 no Windows 10 e 11 e renderiza apps GUI Linux direto no seu desktop Windows. Sem configuração de X server, sem config extra — basta rodar o app:

beadbox

A primeira execução pode levar alguns segundos enquanto o WSLg negocia o display. Depois disso, o Beadbox se comporta como qualquer outra janela nativa: fixe na barra de tarefas, alt-tab para ele, arraste entre monitores. Quando você abrir um workspace, aponte para o caminho do lado Linux (~/meu-projeto), não para o caminho do lado Windows. Dentro do WSL, ~/ é o home certo.

Dica: se você quer um atalho no menu Iniciar, o .deb instala uma entrada .desktop que o Windows expõe automaticamente como "Beadbox (Ubuntu)" ou similar. Procure por ela no menu Iniciar após a instalação.

Já caiu no erro de flock?

Se você instalou o Beadbox.exe e tentou abrir um workspace do WSL, provavelmente viu um erro mencionando flock, falha do modo embutido ou o workspace não carregando. A correção é direta:

  1. Feche o workspace no Beadbox.exe (ou saia do app de vez). O build nativo para Windows não vai funcionar contra esse workspace.
  2. Siga os passos de instalação acima dentro da sua distro WSL2 para instalar o Beadbox para Linux.
  3. Abra o Beadbox de dentro do WSL (rode beadbox no terminal do WSL) e abra o workspace usando seu caminho Linux (~/meu-projeto).

Você pode manter o Beadbox.exe instalado para projetos hospedados no lado Windows (caminhos como C:\Users\voce\meu-projeto). O build para Windows funciona bem para esses — só os projetos hospedados no WSL é que precisam do build para Linux.

Solução de problemas

Avisos do libEGL / Mesa ao iniciar

Quando você executa o beadbox pela primeira vez, o terminal pode imprimir avisos do libEGL, Mesa ou drivers GL sobre aceleração de hardware ausente ou fallback para renderização por software. Isso é normal sob WSLg — o WSL2 não expõe a GPU do Windows diretamente para o lado Linux, então a stack de GUI recorre a caminhos por software. O app inicia normalmente e roda na velocidade total do Beadbox; os avisos são ruído, não erros.

Contexto e referências

Os dois builds (.exe para Windows e .deb para Linux) saem da mesma base de código do Beadbox. O motivo de o .exe não conseguir tocar um workspace do WSL é estrutural, não um bug que pretendemos consertar — a matemática da latência e a ponte do sistema de arquivos jogam contra.

Se você quer o detalhe arquitetural por trás dessa decisão, os briefs de design e o tracer de latência que descartou os caminhos rejeitados estão linkados abaixo.