CLI BitBang

O BitBang CLI é uma ferramenta multitool de acesso remoto em um único binário estático: abra um shell interativo, navegue e transfira arquivos, e acesse aplicativos web na rede da máquina remota a partir de qualquer navegador, sem redirecionamento de porta, sem configuração e sem conta.

Na máquina que você deseja acessar:

curl -sSfL bitba.ng/install | sh
bitbang serve

serve imprime uma URL. Abra-a em qualquer navegador e você terá um terminal, um navegador de arquivos e um proxy para a rede dessa máquina — ou conecte-se de outro terminal com bitbang connect <url> usando o mesmo binário. A conexão é criptografada de ponta a ponta e ponto a ponto; o servidor bitba.ng apresenta as duas extremidades e depois se afasta.

bitbang é um único binário Go estático. Faz parte do projeto BitBang; este whitepaper aborda o design em profundidade.

Emparelhamento com um código de 6 dígitos

Quando você não consegue colar uma URL ou escanear um QR code, como quando está ao telefone ou ao alcance da voz, bitbang serve também imprime um código de emparelhamento curto. A outra parte abre bitba.ng/<code> (ou executa bitbang connect <code>), a tela dela mostra um segundo número de 6 dígitos, e ela lê esse número de volta para você. Você o digita para aprovar. Um intermediário não consegue fazer os dois números coincidirem, e o emparelhamento salva as credenciais de conexão do dispositivo para a próxima vez, ex.: bitbang connect nas1. Se você conhece o Magic Wormhole, o formato é semelhante — um código falado que apresenta duas máquinas com segurança.

Por quê?

• Nada para encaminhar ou configurar. Funciona atrás de NAT, CGNAT ou uma rede restrita — sem alterações no roteador, sem VPN, sem daemon de túnel.
• Nada para instalar no lado que conecta. Um navegador é suficiente. Uma CLI está disponível quando você quer scripts, pipes e cópia de arquivos.
• Privado por design. O tráfego é WebRTC/DTLS, ponto a ponto. O servidor de sinalização nunca o vê; se um caminho direto não for possível, um relay TURN carrega apenas texto cifrado.
• Sem conta, sem telemetria.

Por que não simplesmente usar SSH?

bitbang tem o formato do ssh: serve, connect e cp mapeiam para sshd, ssh e scp, com WebRTC como transporte em vez de TCP. Para uma máquina na qual você já consegue entrar confortavelmente via SSH, essa diferença não traz muito benefício. Mas a maior parte do bitbang surgiu de inconvenientes que pareço encontrar com mais frequência do que deveria:

Alcance. O acesso SSH remoto precisa de um caminho de entrada, e na maioria das redes abrir um não é uma decisão sua — CGNAT (celular, Starlink, muitos provedores de internet), redes corporativas, universitárias, municipais. Então, na prática, você adiciona um segundo sistema: Tailscale, uma VPN, ngrok — outra instalação, outra conta, outro daemon para manter rodando. bitbang serve não precisa de porta aberta e funciona de qualquer lugar.

Configuração. O SSH precisa ser habilitado e configurado antes de deixar você entrar. Ele vem desabilitado por padrão no Raspberry Pi OS e, muitas vezes, apenas com chave, o que significa colocar sua chave pública na máquina primeiro. E como você faz isso? E-mail ou um pendrive geralmente são as opções mais indolores. bitbang configura a conexão com uma troca de código de 6 dígitos — algo que você pode fazer com segurança pelo telefone ou gritando do outro lado da sala. Ele também roda como um usuário comum — sem root, sem daemon, sem arquivo de configuração.

Proxy. Se você quer um aplicativo web na rede dessa máquina, o SSH oferece um túnel separado por aplicativo, nomeado antecipadamente. O proxy do bitbang é genérico: especifique a URL do aplicativo web no momento da conexão.

Cliente de navegador. O SSH precisa de um cliente SSH e uma chave ou senha no lado que conecta. bitbang precisa de um navegador — o que significa um telefone, um laptop emprestado ou alguém que nunca abriu um terminal. Entregue a URL e a pessoa terá o acesso que você concedeu.

Usando o bitbang

Toda conexão tem duas extremidades: um ouvinte (bitbang serve, executando na máquina que está sendo acessada) e um conector (um navegador, ou a CLI bitbang, na máquina que está acessando). Uma URL do ouvinte atende aos dois tipos de conector.

O ouvinte: bitbang serve

bitbang serve                    # tudo: shell + arquivos + proxy em uma URL
bitbang serve shell              # apenas shell
bitbang serve files ~/share      # apenas arquivos (adicione -upload para permitir uploads)
bitbang serve proxy              # proxy; escolha o destino no navegador
bitbang serve proxy localhost:8080   # ...ou fixe um único destino

Cada um imprime um QR code, uma URL e um código de emparelhamento.

Conectando-se a partir de um navegador

Abra a URL. Dependendo do que está sendo servido, você obtém:

• Shell — um terminal completo na página (cores, redimensionamento, copiar/colar).
• Arquivos — navegar, visualizar, baixar e enviar.
• Proxy — digite um endereço LAN (nas.local, 192.168.1.10:8080, localhost:3000/admin) e use o aplicativo como se estivesse local. Logins, cookies, uploads e streaming funcionam.

Conectando-se a partir da CLI

bitbang connect <url>                                   # shell interativo
bitbang connect <url> -- tail -f /var/log/syslog        # comando de execução única
bitbang cp <url>:/var/log/app.log ./app.log             # copiar arquivos, estilo scp
bitbang cp - <url>:/tmp/firmware.bin < firmware.bin     # stdin/stdout também funcionam

Toda conexão ou emparelhamento bem-sucedido é salvo em ~/.bitbang/devices.json, então, a partir daí, um nome curto é suficiente: bitbang connect nas1.

Instalação

O comando de uma linha detecta sua arquitetura (amd64, arm64, armv7), baixa o binário do release mais recente do GitHub, verifica seu SHA-256 contra o checksums.txt do release e instala em ~/.local/bin/bitbang.

Fixe uma versão, altere o local ou audite o script primeiro:

curl -sSfL bitba.ng/install | sh -s -- --version v0.5.0
curl -sSfL bitba.ng/install | sh -s -- --prefix /usr/local/bin

curl -sSfL bitba.ng/install -o install.sh && less install.sh && sh install.sh

As versões para macOS e Windows estão a caminho — issues foram abertas para cada uma (macOS, windows; basta reagir ou postar para mostrar que você está interessado. Instalação manual: baixe o binário de Releases e coloque-o no seu PATH. Compilar a partir do código-fonte: veja abaixo.

Como funciona a URL de instalação

bitba.ng/install é um redirecionamento, não um script hospedado. A cadeia:

1. curl acessa https://bitba.ng/install, que redireciona (302) para install.sh neste repositório (no branch main).
2. O script é executado no seu shell, detecta o sistema operacional e a arquitetura e baixa o binário de https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>.
3. Ele busca checksums.txt do mesmo release e verifica o SHA-256 do binário.
4. Instala em ~/.local/bin (sobrescrevível).

O script de instalação vive neste repositório, ao lado do código que ele instala — para que você possa revisá-lo junto com o binário, e o host canônico bitba.ng é dono apenas da URL curta. Quem faz self-hosting pode apontar o /install do próprio host para qualquer script que desejar: a variável de ambiente INSTALL_URL do servidor de sinalização controla o destino do redirecionamento (vazia → 404).

Segurança

• Identidade autocomprovada. Na primeira execução, bitbang gera um par de chaves RSA em ~/.bitbang/<program>/; o UID do dispositivo é derivado da chave pública, então personificar um dispositivo significa encontrar uma segunda pré-imagem do seu UID.
• O segredo nunca toca o servidor. O código de acesso vive no fragmento da URL (#…), que os navegadores nunca enviam — bitba.ng intermediaria a conexão sem jamais ver a credencial que a autoriza.
• Criptografia de ponta a ponta. Todo o tráfego usa o DTLS do WebRTC. O servidor de sinalização vê apenas a chave pública, o UID derivado e metadados de conexão — nunca os seus dados. Um relay TURN, se necessário, vê apenas texto cifrado.
• Emparelhamento verificado. O número lido em voz alta no emparelhamento por código é uma string de autenticação curta (SAS), calculada de forma independente em ambas as extremidades a partir das impressões digitais DTLS negociadas e de dois nonces comprometidos — um intermediário, cujas impressões digitais necessariamente diferem, não consegue fazer os dois números coincidirem.
• PIN opcional (--pin) para configurações permanentes ou headless, e modo descartável (-ephemeral) para uma identidade nova a cada execução.

Como as duas extremidades se autenticam mutuamente sem confiar no servidor de sinalização é abordado em detalhes aqui: Trustless Signaling: Authentication Without a Central Authority.

Como se compara

Referência de comandos

As flags aceitam ambas as formas (-pin ou --pin). Flags booleanas ficam desligadas por padrão, salvo indicação em contrário.

bitbang serve [flags]                  Todas as capacidades: shell + arquivos + proxy em uma URL
bitbang serve shell [flags]            Apenas shell
bitbang serve files [PATH] [flags]     Apenas arquivos (PATH padrão é o diretório atual)
bitbang serve proxy [TARGET] [flags]   Proxy reverso HTTP/WebSocket (TARGET fixa um host:porta)
bitbang connect <target> [-- cmd …]    Shell cliente (interativo ou de execução única)
bitbang cp <src> <dst>                 Copiar arquivos (um lado é <URL>:/path, ou '-')
bitbang version                        Exibe a versão (também --version)
bitbang help                           Uso (também --help, -h)

bitbang serve — executar um ouvinte

Flags compartilhadas (todas as quatro formas de serve):

Flags de shell (serve e serve shell):

Flags de arquivos:

(Avançado: -video-fd N transmite um FD de socketpair herdado para um auxiliar de vídeo externo; para uso interno/embutido.)

bitbang connect <target> [-- comando …] — shell cliente

<target> pode ser qualquer um dos seguintes:

• um nome salvo — ex.: nas1; resolvido pela tabela de hosts conhecidos (veja abaixo)
• um código de emparelhamento de 6 dígitos — ex.: 482731; executa o fluxo de emparelhamento e depois conecta
• uma URL — https://bitba.ng/<id>#<code>, bitba.ng/<id>#<code> ou apenas <id>#<code>

Sem -- comando, abre um shell interativo (um PTY quando o stdin é um terminal). Com -- comando args…, executa esse único comando de forma não interativa e encerra com o status dele (saídas por sinal são reportadas como 128).

bitbang cp <src> <dst> — copiar arquivos

Exatamente um de <src> / <dst> é remoto, escrito <URL>:/path (URL em qualquer forma aceita por connect). - significa stdin/stdout, então cp <URL>:/f - transmite para o stdout e cp - <URL>:/f envia do stdin. Uma / ou . final no lado local mantém o nome base remoto (estilo scp).

Nomes de dispositivo e a tabela de hosts conhecidos

Toda conexão ou emparelhamento bem-sucedido é lembrado em ~/.bitbang/devices.json (modo 0600), para que você possa reconectar por um nome curto em vez de uma URL ou código:

bitbang connect 482731 -name nas1     # emparelha uma vez, salva como "nas1"
bitbang connect nas1                  # daqui em diante, apenas o nome

• -name NAME escolhe o nome; ele se aplica apenas a um host novo. Sem ele, um nome automático (device1, device2, …) é atribuído e impresso (Saved as "device1".).
• Regras de nomenclatura: um nome deve começar com uma letra e conter apenas letras, dígitos, - ou _. Isso garante que ele nunca possa ser confundido com um código de 6 dígitos ou uma URL. Consultas e unicidade não diferenciam maiúsculas de minúsculas.
• Sem renomeação via connect: bitbang connect nas1 -name nas2 é rejeitado — -name é apenas para salvamentos na primeira vez.
• Quando é salvo: um emparelhamento é registrado assim que o SAS é verificado (para que uma reconexão instável não o perca); uma conexão por URL é registrada uma vez conectada.
• Cada entrada armazena {name, uid, access_code, server, paired_at}. Reconectar um host conhecido (por nome ou URL) atualiza a entrada no lugar e mantém o nome.

Compilando a partir do código-fonte

Requer Go 1.25+. Go puro, linkado estaticamente (CGO_ENABLED=0) — compilação cruzada trivial, sem dependências de runtime.

go build ./cmd/bitbang/

# compilação cruzada:
GOOS=linux   GOARCH=arm64        go build -o bitbang-arm64 ./cmd/bitbang/
GOOS=linux   GOARCH=arm GOARM=7  go build -o bitbang-armv7 ./cmd/bitbang/
GOOS=windows GOARCH=amd64        go build -o bitbang.exe   ./cmd/bitbang/
GOOS=darwin  GOARCH=arm64        go build -o bitbang-macos ./cmd/bitbang/

Diagramas

Roadmap

Disponível hoje: shell, arquivos e proxy, acessíveis pelo navegador ou pela CLI, além de cópia de arquivos estilo scp e emparelhamento ad-hoc com uma tabela de dispositivos salva. Projetado e a caminho:

• Ponte serial — controlar um /dev/ttyUSB0 remoto a partir de uma porta virtual local (ex.: usar o Arduino IDE pela internet). Uma issue foi aberta aqui.
• Encaminhamento de porta TCP — -L 5432:db.internal:5432 para alcançar serviços apenas na LAN. Uma issue foi aberta aqui.
• Área de trabalho remota — tela por uma trilha de vídeo WebRTC, teclado/mouse pelo canal de dados.

Licença

MIT — veja LICENSE.

Contribuindo

Issues e PRs são bem-vindos.