
Estabeleça acesso remoto seguro a uma máquina com shell interativo, transferência de arquivos e proxy web sobre WebRTC peer-to-peer criptografado de ponta a ponta, usando um navegador ou CLI sem encaminhamento de portas ou contas.
# BitBang CLI
[](https://github.com/richlegrand/bitbang-cli/actions/workflows/tests.yml)

`bitbang` é uma ferramenta multifuncional de acesso remoto em um único binário estático. A partir de qualquer navegador: acesso a um shell interativo e a um navegador de arquivos na máquina remota. Você também pode acessar aplicações web na rede dessa máquina. Além do navegador, ele faz encaminhamento de portas TCP, cópia de arquivos e compartilhamento de terminal. Não requer conta nem configuração -- simplesmente funciona.

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ê obtém um terminal, um navegador de arquivos e um proxy para a rede daquela máquina -- ou alcance a mesma máquina a partir de outro terminal com `bitbang connect <url>`, que adiciona encaminhamento de portas (`-L`) e cópia de arquivos (`bitbang cp`). A conexão é criptografada de ponta a ponta e ponto a ponto; o servidor `bitba.ng` apresenta as duas pontas e depois sai de cena.
`bitbang` é um único binário Go estático. Ele faz parte do [projeto BitBang](https://github.com/richlegrand/bitbang); este [whitepaper](https://github.com/richlegrand/bitbang/blob/main/whitepaper.md) aborda o design em profundidade.
## Como se compara
| | ngrok | Tailscale | `bitbang` |
| ------------------------------ | ---------------------- | ------------------------------ | ------------------- |
| Configuração antes do primeiro uso | Conta + authtoken | Conta + login em cada dispositivo | **Execute um comando** |
| Para compartilhar algo, você executa | um servidor web, mais o ngrok | o cliente deles em ambas as máquinas | **`bitbang serve`** |
| O que um navegador na outra ponta recebe | o servidor web que você já estava executando | nada -- ele precisa do cliente deles | **um terminal, um navegador de arquivos e aplicativos web na rede remota** |
| Caminho dos dados | os servidores deles | P2P (fallback por relay) | **P2P (fallback por relay)** |
| Criptografado de ponta a ponta | Não por padrão | Sim | **Sim** |
## Receitas rápidas
**Alcançar um serviço em casa**
- [Monte seu NAS doméstico de qualquer lugar (SMB)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#mount-your-home-nas-from-anywhere-smb)
- [Assista à sua biblioteca de mídia de qualquer lugar (Jellyfin)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-your-media-library-from-anywhere-jellyfin)
- [Use seu próprio LLM de qualquer lugar (Ollama, Open WebUI)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#use-your-own-llm-from-anywhere-ollama-open-webui)
- [Verifique suas câmeras de segurança (Frigate)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-security-cameras-frigate)
- [Alcance sua automação residencial sem expô-la (Home Assistant)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-your-home-automation-without-exposing-it-home-assistant)
- [Imprima na sua impressora doméstica (IPP, CUPS)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#print-to-your-home-printer-ipp-cups)
**Acessar uma máquina**
- [Obtenha um shell em uma máquina atrás de NAT](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-on-a-machine-behind-nat)
- [Obtenha um shell a partir do seu celular](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-from-your-phone)
- [Área de trabalho remota em uma máquina Windows (RDP)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#remote-desktop-into-a-windows-machine-rdp)
- [Alcance uma área de trabalho Linux ou Mac (VNC)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-linux-or-mac-desktop-vnc)
- [SSH para uma máquina sem porta aberta (OpenSSH)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#ssh-to-a-machine-with-no-open-port-openssh)
- [Configure um Raspberry Pi headless](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#set-up-a-headless-raspberry-pi)
**Compartilhar com outra pessoa**
Compartilhar significa simplesmente dar a alguém uma URL única ou um código QR que lhe concede acesso. As permissões podem ser personalizadas e definidas para expirar em minutos, horas, etc.
- [Compartilhe arquivos sem enviá-los para lugar nenhum](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#share-files-without-uploading-them-anywhere)
- [Mostre seu projeto para alguém](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-your-project)
- [Mostre a alguém o erro em que você está travado](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-the-error-you-are-stuck-on)
- [Conceda a alguém um acesso que expira](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#give-someone-access-that-expires)
- [Verifique sua sessão de agente pelo celular (Claude Code, tmux)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-agent-session-from-your-phone-claude-code-tmux)
- [Conserte o roteador de outra pessoa](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#fix-someone-elses-router)
**Desenvolvimento e dispositivos**
- [Acesse um banco de dados a partir da sua máquina de desenvolvimento (Postgres, MySQL)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-database-from-your-dev-machine-postgres-mysql)
- [Sincronize dispositivos que não conseguem se encontrar (Syncthing)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#sync-devices-that-cannot-find-each-other-syncthing)
- [Observe um robô a partir do navegador (ROS, Foxglove)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-a-robot-from-a-browser-ros-foxglove)
**Técnicas**
- [O que um listener de encaminhamento expõe](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#what-a-forwarding-listener-exposes)
- [Permita que outras máquinas na sua LAN usem um encaminhamento](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#let-other-machines-on-your-lan-use-a-forward)
- [Sabe-se que não funciona](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#known-not-to-work)
## Usando o `bitbang`
Toda conexão tem duas pontas: um **listener** (`bitbang serve`, em execução na máquina que está sendo acessada) e um **connector** (um navegador, ou a CLI `bitbang`, na máquina que está acessando). Uma única URL de listener atende os dois tipos de connector.
### O listener: `bitbang serve`
```
bitbang serve # everything: shell + proxy + files + forward
bitbang serve shell # just a terminal
bitbang serve files ~/share # just a directory (-files-upload to allow uploads)
bitbang serve proxy localhost:8080 # just one web app, straight at the URL
bitbang serve proxy a.lan:80,b.lan:80 # ...or several, chosen in the browser
bitbang serve forward 127.0.0.1:22 # just TCP, for `connect -L`
bitbang serve shell files ~/share proxy nas.lan:8096 # any combination
```
Cada um imprime um código QR, URL e um código de emparelhamento. O modo define o que o
listener pode fazer: `serve shell` não tem encaminhamento a conceder, e um
listener apenas de encaminhamento nunca inicia um shell, portanto não há nada a escalar.
Um padrão que vale a pena conhecer: **o encaminhamento e o proxy alcançam qualquer host:porta que o
listener consiga alcançar**, não apenas aquele que você tinha em mente, então um link entregue
para um banco de dados também alcança o resto daquela rede. Nomear os alvos após a
palavra restringe isso -- `forward db.internal:5432` alcança esse e nada mais.
### Compartilhando uma sessão em execução: `bitbang share`
`serve shell` inicia um novo shell. `share` publica uma sessão tmux que já
está em execução:
```
bitbang share # publish the current tmux session
bitbang share --read-only # publish without a control URL
bitbang share status|stop|rotate
```
O comando retorna após a publicação, então `Ctrl-Z`, `bitbang share`, `fg`
funciona para uma tarefa já em andamento. O hospedagem requer tmux 3.2+ no Unix ou
WSL. Clientes Windows nativos podem abrir as URLs, mas não podem hospedar um compartilhamento.
Por padrão, o comando imprime duas URLs de portador:
- A **URL de Controle** pode digitar com a mesma autoridade que o teclado local.
Apenas um controlador pode se conectar por vez.
- A **URL de Visualização** é somente leitura. A entrada é descartada antes de chegar ao tmux, e
até `--max-viewers` visualizadores podem se conectar ao mesmo tempo (padrão 16).
`--read-only` omite completamente a credencial de controle. Os limites de visualizador e controlador
são mantidos durante toda a vida de cada conexão, mesmo antes de ela abrir um shell.
Os compartilhamentos são executados até serem interrompidos por padrão; `--ttl` define um tempo de vida (por exemplo, `--ttl 1h`).
As URLs de compartilhamento são efêmeras e nunca são salvas em `devices.json`. `share stop`,
a expiração do TTL ou a remoção da sessão de origem desconecta os pares remotos sem
interromper a sessão de origem.
Executar novamente `bitbang share` reimprime as URLs do compartilhamento em execução. Se você
passar uma flag que não concorda com o que está em execução (digamos, `--read-only`
contra um compartilhamento que tem uma URL de controle), ele informa isso em vez de
devolver as URLs antigas; `bitbang share rotate` substitui o compartilhamento
por um que usa as novas flags.
Um worker em segundo plano é executado em uma sessão de gerenciamento tmux `_bbshare_*` destacada,
portanto, não há daemon ou arquivo PID para gerenciar.
O compartilhamento não altera nenhuma opção do tmux. Com o `window-size latest` padrão do tmux, a
janela segue o cliente ativo de leitura e escrita; um visualizador solitário ainda fornece o
único tamanho disponível. Se `window-size` foi substituído, `share` relata isso
mas não altera a configuração do usuário.
### Distribuindo acesso limitado: `bitbang link`
Um listener, uma URL e quantos **links de acesso** você precisar. Cada um é um
código separado na mesma URL, concedendo um subconjunto do que o listener oferece
e, opcionalmente, expirando em um horário fixo:
```
bitbang link edit # add entries in $EDITOR
bitbang link ls # what you have handed out
bitbang link rm <label> # revoke one
bitbang link qr <label> # its URL and QR code
```
Uma entrada é uma linha de JSON em `~/.bitbang/bitbang/links.json`. Escreva uma sem código, recarregue o listener no seu console, e ele gera uma:
```json
[
{"label": "ana", "grant": "files", "expires": "2026-09-01T00:00:00Z"},
{"label": "ben", "grant": "files /srv/photos"},
{"label": "dev", "grant": "shell forward 127.0.0.1:5432"}
]
```
```
0) owner files forward proxy shell
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#_vtQ0JCPe7s
1) ana files expires in 6d
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#T-Ty_HhvLfY
2) ben files /srv/photos
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#L6La8OzBO74
3) dev forward 127.0.0.1:5432 shell
https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#8kmI3LYzB7E
```
`owner` é o código da própria identidade e concede tudo o que o listener serve; envie
um dos outros em vez disso. O console aceita tanto o rótulo quanto o número ao lado
dele, então `rm 2` e `rm ben` fazem a mesma coisa.
Um `grant` é escrito com as palavras que `serve` aceita, e só pode restringir o que o
listener já serve. Isso significa que um link não se limita a escolher capacidades:
ele pode nomear um subdiretório da pasta compartilhada, um subconjunto dos alvos de encaminhamento, ou
um único comando para `shell`. Omita `grant` e o link concede o que quer que o listener
faça. Peça algo fora do alcance do listener e o console recusa com
a mesma mensagem que `serve` daria a você.
O rótulo é o que identifica um link, não os seus termos, então duas pessoas podem ter links
com grants e expiração idênticos e você ainda pode revogar um sem tocar no
outro.
Revogação e expiração alcançam sessões que já estão abertas: a conexão fecha
e o detentor é informado do motivo, em vez de ficar no silêncio. E um código expirado é
aposentado em vez de pausado -- renovar uma entrada cunha uma nova, então a URL que você
já enviou permanece morta.
### Onde o BitBang guarda seus arquivos
Tudo o que o BitBang armazena sobre si mesmo vive em um único diretório: o par de chaves
de identidade que fixa sua URL, a tabela de links, a tabela de dispositivos salvos que `connect`
e `cp` leem, e o estado de compartilhamento. Por padrão, isso é `~/.bitbang`.
Um serviço frequentemente não consegue usar `~`. `-home` define o diretório, e `BITBANG_HOME`
faz o mesmo sem repetir a flag em cada comando:
```
bitbang serve shell -home /var/lib/bitbang
BITBANG_HOME=/var/lib/bitbang bitbang link ls
```
A flag está em todos os comandos, não apenas em `serve`, porque o diretório
não pertence ao serve -- esquecê-la uma vez em `bitbang link` editaria uma tabela
diferente.
A ordem completa, a primeira correspondência vence:
| Definição | Diretório usado |
|---|---|
| `-home <dir>` | exatamente esse |
| `$BITBANG_HOME` | exatamente esse |
| `$STATE_DIRECTORY` | exatamente esse -- o systemd o define a partir de `StateDirectory=`, então uma unit não precisa de mais nada |
| `$XDG_STATE_HOME` | `$XDG_STATE_HOME/bitbang` |
| `$HOME` | `$HOME/.bitbang` |
| nenhum deles | nada: o BitBang para e informa isso |
Os três primeiros nomeiam o próprio diretório; os dois últimos nomeiam um pai
do qual ele pende.
Essa última linha importa em uma máquina onde o usuário do serviço não tem home. Versões
anteriores recorriam ao diretório de trabalho, então um listener iniciado sem
`HOME` gravava seu par de chaves onde quer que tivesse iniciado -- `/` para um script
init. Agora ele se recusa em vez de colocar uma chave privada em algum lugar que ninguém
escolheu.
O listener nomeia o diretório na inicialização, então você nunca precisa descobrir
qual destes venceu:
```
Home: /home/you/.bitbang
Home: /var/lib/bitbang (STATE_DIRECTORY)
```
Portanto, uma unit systemd não precisa de nenhuma configuração específica do BitBang para isso:
```ini
[Service]
StateDirectory=bitbang
ExecStart=/usr/local/bin/bitbang serve shell
```
### Emparelhamento com um código de 6 dígitos
Quando não consegue colar um URL ou ler um código QR, como quando está ao telefone, ou a uma distância em que é preciso gritar, o `bitbang serve` também imprime um **código de emparelhamento** curto. A outra parte abre `bitba.ng/<code>` (ou executa `bitbang connect <code>`), o ecrã dela mostra um segundo número de 6 dígitos, e ela lê *esse* número de volta para si. Você introduz-o para aprovar. Um atacante no meio não consegue fazer com que os dois números coincidam, e o emparelhamento guarda as credenciais de ligação do dispositivo para a próxima vez, por exemplo `bitbang connect nas1`. Se conhece o [Magic Wormhole](https://github.com/magic-wormhole/magic-wormhole), a forma é semelhante -- um código falado que apresenta duas máquinas de forma segura.

### Traga o seu próprio TURN
A maioria das ligações vai diretamente ponto-a-ponto. Quando ambas as extremidades estão atrás de um NAT que
não permite hole-punching, o tráfego precisa de um relay, e por predefinição esse relay é o nosso. `-ice-servers`
aponta o listener para o seu próprio:
```
bitbang serve -ice-servers ~/turn.json
```
O listener entrega a configuração ao servidor de sinalização no momento do registro, e o servidor
a entrega a quem se conectar -- assim ambas as pontas usam o seu relay e o nosso nunca é envolvido.
Qualquer coturn, ou um provedor hospedado como Cloudflare ou Twilio, funciona.
O arquivo é JSON, em qualquer uma destas três formas que o seu provedor lhe entregou:
```json
[{"urls": ["turn:turn.example.net:3478"], "username": "user", "credential": "pass"}]
```
```json
{"ice_servers": [{"urls": "stun:stun.example.net:3478"}]}
```
```json
{"iceServers": [{"urls": ["turn:turn.example.net:3478"], "username": "u", "credential": "p"}]}
```
`urls` aceita uma string ou uma lista; `username` e `credential` são para TURN e podem ser
omitidos em uma entrada apenas STUN. O caminho pode ser absoluto, relativo ou com raiz em `~`. Um arquivo
que não é analisado interrompe o listener na inicialização em vez de recorrer silenciosamente a um fallback.
Se uma sessão acabar sendo retransmitida por relay sem que isso tenha sido solicitado, `bitbang connect` informa isso
em vez de deixar você se perguntando por que parece lento. O listener registra isso
de qualquer forma (`via RELAY`), e `-relay` / `-norelay` forçam a questão em um sentido
ou no outro quando você está diagnosticando um caminho.
Vale dizer: isso diz respeito a quem transporta os bytes, não a quem pode lê-los. Um relay só
vê texto cifrado DTLS, inclusive o nosso. Execute o seu próprio quando precisar de mais TURN do que podemos fornecer (atualmente limitamos o tempo).
### Conectando a partir de um navegador
Abra a URL. Dependendo do que for servido, você obtém:
- **Shell** -- um terminal completo na página (cores, redimensionamento, copiar/colar).
- **Files** -- navegue, visualize, baixe e envie arquivos.
- **Proxy** -- digite um endereço da LAN (`nas.local`, `192.168.1.10:8080`, `localhost:3000/admin`) e use o aplicativo como se estivesse localmente. Logins, cookies, uploads e streaming funcionam.
<!-- TODO: per-feature demos -->
<!-- Remote shell in a browser tab -->
<!-- Streaming Jellyfin through the proxy -->
### Conectando a partir da CLI
```
bitbang connect <url> # interactive shell
bitbang connect <url> -- tail -f /var/log/syslog # one-shot command
bitbang connect <url> -L 15432:db.internal:5432 # local TCP forwarding
bitbang connect <url> -L 14450:nas.local:445 -L 15900:[fd00::20]:5900
bitbang cp <url>:/var/log/app.log ./app.log # copy files, scp-style
bitbang cp - <url>:/tmp/firmware.bin < firmware.bin # stdin/stdout work too
```
`-L` encaminha **apenas TCP**, como `ssh -L`. `-L` vincula a `127.0.0.1` a menos que você passe
`-g`, o que torna a porta encaminhada acessível a partir da sua rede local -- e
qualquer pessoa que a alcance obtém o que quer que o túnel alcance, sem nenhuma
credencial BitBang à frente.
O listener precisa de `bitbang serve forward` ou `bitbang serve`. Por padrão, um
link `forward` alcança **qualquer host:porta que o listener consiga alcançar**, não apenas
aquele que você tinha em mente, então um link concedido para um banco de dados também alcança o restante
dessa rede. Restrinja-o nomeando o que ele pode alcançar:
```
bitbang serve forward db.internal:5432 # this link reaches one service
```
Cada conexão ou emparelhamento bem-sucedido é salvo em `~/.bitbang/devices.json`, então a partir daí um nome curto é suficiente: `bitbang connect nas1`.
## Suporte a plataformas
Um binário por plataforma, sem dependências de runtime. Tudo funciona
em todos os lugares, exceto nas duas linhas destacadas abaixo.
| | Linux | macOS | Windows |
| ---------------------------------------- | :---: | :---: | :-----: |
| Shell, arquivos, proxy (`bitbang serve`) | sim | sim | sim |
| Encaminhamento TCP (`-L`) | sim | sim | sim |
| Links de acesso -- concessão, expiração, revogação | sim | sim | sim |
| Traga seu próprio TURN | sim | sim | sim |
| Emparelhamento com um código de 6 dígitos | sim | sim | sim |
| O console do listener (Enter) | sim | sim | sim |
| `bitbang connect`, `bitbang cp` | sim | sim | sim |
| Visualizar uma sessão compartilhada | sim | sim | sim |
| **Hospedar um compartilhamento** (`bitbang share`) | sim | sim | não * |
| **Redimensionamento do terminal enquanto conectado** | sim | sim | não ** |
\* `bitbang share` publica uma sessão tmux, então hospedar uma requer tmux --
Linux, macOS ou WSL. O Windows nativo ainda pode abrir URLs de compartilhamento com
`bitbang connect`.
\*\* Um conector Windows não percebe quando seu terminal é redimensionado, então o
shell remoto mantém o tamanho com o qual iniciou até você reconectar. O Unix
obtém isso do `SIGWINCH`, do qual o Windows não tem equivalente.
## Segurança
- **Identidade autocertificada.** Na primeira execução, 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 de seu UID.
- **O segredo nunca toca o servidor.** O código de acesso fica no fragmento da URL (`#…`), que os navegadores nunca enviam -- o `bitba.ng` intermedeia a conexão sem jamais ver a credencial que a autoriza.
- **Criptografia de ponta a ponta.** Todo o tráfego passa pelo DTLS do WebRTC. O servidor de sinalização vê apenas a chave pública, o UID derivado e metadados de conexão -- nunca 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 independentemente em ambas as pontas a partir das impressões digitais DTLS negociadas e de dois nonces comprometidos -- um ataque de intermediário (machine-in-the-middle), cujas impressões digitais necessariamente diferem, não consegue fazer os dois números coincidirem.
- **A URL é uma credencial portadora.** Qualquer um que a tenha obtém o que você escolheu servir -- um shell, se você executou `serve shell`. Compartilhe-a com cuidado.
- **PIN opcional** (`--pin`) para configurações permanentes ou headless, e **modo descartável** (`-ephemeral`) para uma identidade nova a cada execução.
- **O que o servidor ainda vê.** Não é nada. Ele intermedeia a apresentação, então
observa os endereços IP de ambas as pontas, quando elas se conectam e quanto elas
trocam. A criptografia de ponta a ponta o mantém fora dos seus dados, não dos
metadados ao redor deles -- *confiança mínima* é uma descrição mais justa do que
*sem confiança*.
- **Um navegador confia na página que carregou.** O cliente de navegador é JavaScript
servido pelo servidor de sinalização, então abrir uma URL significa confiar que esse servidor
serve código honesto. O `bitbang connect` não tem essa dependência: é um
binário que você instalou e verificou por checksum. Se essa distinção importa para você,
conecte-se com a CLI.
Como as duas pontas se autenticam mutuamente, de modo que o servidor de sinalização não possa
se inserir na conexão, é abordado em detalhes aqui: [*Trustless Signaling: Authentication Without a Central Authority*](https://github.com/richlegrand/bitbang/blob/main/trustless-signaling.md).
## Por quê?
- **Nada para abrir ou configurar.** Funciona por trás de NAT, CGNAT ou de uma rede restrita — sem alterações no router, sem VPN, sem daemon de túnel.
- **Nada para instalar do lado de quem se liga.** Um navegador é suficiente. Uma CLI está disponível quando quiser scripting, pipes e cópia de ficheiros.
- **Privado por conceção.** O tráfego é WebRTC/DTLS, ponto-a-ponto. O servidor de sinalização nunca o vê; se não for possível um caminho direto, um relay TURN transporta apenas texto cifrado.
- **Sem conta, sem telemetria.**
### Porquê não usar apenas SSH? Ou Tailscale?
Resposta curta: para uma máquina na qual já consegue fazer SSH, ou para um conjunto dos seus próprios
dispositivos nos quais pode instalar, continue a usar o que já tem. O `bitbang` serve para quando o
lado remoto é uma pessoa em vez de um dispositivo, ou quando não pode instalar nada
onde está. Ambas as questões são respondidas em detalhe nas
**[FAQ](https://github.com/richlegrand/bitbang-cli/blob/main/FAQ.md)**.
## Instalação
```
curl -sSfL bitba.ng/install | sh
```
Linux e macOS. Detecta seu SO e arquitetura (`amd64`, `arm64` e `armv7` no Linux), baixa o binário da última [versão do GitHub](https://github.com/richlegrand/bitbang-cli/releases), verifica seu SHA-256 em relação ao `checksums.txt` da versão e instala em `~/.local/bin/bitbang`.
As builds para Windows são publicadas como `bitbang-windows-amd64.exe` e
`bitbang-windows-arm64.exe`. Baixe o binário apropriado em Releases,
renomeie-o para `bitbang.exe` e coloque-o no seu `PATH`.
**Compilar a partir do código-fonte:** veja [abaixo](#building-from-source).
**macOS e Gatekeeper.** O instalador de uma linha acima não é afetado: o `curl` não
define o atributo `com.apple.quarantine`, então o binário que ele baixa é executado
normalmente. Se, em vez disso, você baixar `bitbang-darwin-arm64` da página de Releases
em um navegador, o macOS o coloca em quarentena e se recusa a abri-lo, porque os binários
da versão não são notarizados. Remova a quarentena com qualquer um dos seguintes:
```
xattr -d com.apple.quarantine ./bitbang-darwin-arm64
```
ou clique com o botão direito no arquivo no Finder e escolha Abrir, o que oferece uma substituição única. Como alternativa, compile a partir do código-fonte, o que nunca aplica quarentena.
**Windows e SmartScreen.** A mesma coisa acontece no Windows, pelo mesmo motivo. Um download feito pelo navegador anexa a Mark-of-the-Web, então a primeira execução mostra *"O Windows protegeu o seu PC"* -- escolha **Mais informações** e depois **Executar assim mesmo**. Os binários da release não são assinados digitalmente, então isso é esperado e não um sinal de que algo está errado. Baixar o `.exe` com `curl` ou com o `Invoke-WebRequest` do PowerShell não anexa essa marca, e compilar a partir do código-fonte também não.
### Opções de instalação
Fixe uma versão, altere o local ou leia o script antes de executá-lo:
```
curl -sSfL bitba.ng/install | sh -s -- --version 0.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 tags de release não têm o prefixo `v` (`0.5.0`, não `v0.5.0`).
### Como funciona a URL de instalação
`bitba.ng/install` é um redirecionamento, não um script hospedado. A cadeia:
1. O `curl` acede a `https://bitba.ng/install`, que faz um 302 para [`install.sh`](https://github.com/richlegrand/bitbang-cli/blob/main/install.sh) neste repositório (no ramo `main`).
2. O script é executado na sua shell, deteta o SO e a arquitetura, e descarrega o binário a partir de `https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>`.
3. Obtém o `checksums.txt` da mesma release e verifica o SHA-256 do binário.
4. Instala em `~/.local/bin` (configurável).
O script de instalação reside neste repositório, junto ao código que instala -- assim pode revê-lo a par do binário, e o host canónico bitba.ng apenas detém a URL curta. Quem aloja o seu próprio servidor pode apontar o `/install` do seu host para o script que distribuir: a variável de ambiente `INSTALL_URL` do servidor de sinalização controla o destino do redirecionamento (vazia → 404).
## Referência de comandos
Todos os subcomandos e flags estão em **[CLI.md](https://github.com/richlegrand/bitbang-cli/blob/main/CLI.md)**, e `bitbang <command>
--help` imprime o mesmo no terminal.
## Compilar a partir do código-fonte
Requer Go 1.25+. Go puro, ligado estaticamente (`CGO_ENABLED=0`) -- compilação cruzada trivial, sem dependências de runtime.
```
go build ./cmd/bitbang/
# cross-compile:
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/
```
A partir do Prompt de Comando do Windows:
```bat
go build -o bitbang.exe .\cmd\bitbang
go test .\...
run_tests.cmd unit
```
Comandos de shell, compartilhamento de arquivos, proxy e o cliente CLI são suportados no
Windows. Shells interativos de navegador e CLI usam Windows ConPTY, incluindo
eco de entrada do terminal, edição de linha, saída VT e eventos de redimensionamento. O ConPTY requer
Windows 10 versão 1809 ou Windows Server 2019 ou posterior.
## Diagramas
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/47068/d68fcddad62ab84f11a549906a2b5abf2330fb25f39b3c1a1266eac7257a080d.png" alt="shell e compartilhamento de arquivos do bitbang CLI" width="760">
<img src="https://assets.kitploit.com/production/public/readmes/47068/55bb6866c22504a6434e3dee8cb998e747cd73cb9d0bfa5e0bc0ede7b90ce262.png" alt="operação de proxy do bitbang CLI" width="720">
</p>
## Roadmap
Disponível hoje: **shell, arquivos e proxy**, acessíveis pelo navegador ou pela CLI, além de **encaminhamento de porta TCP**, cópia de arquivos no estilo scp, **pareamento ad-hoc** com uma tabela de dispositivos salva, **compartilhamento de terminal** (`bitbang share`) e **links de acesso** (`bitbang link`) que restringem e expiram o que uma URL concede. Projetado e a caminho:
- **Ponte serial** -- controlar um `/dev/ttyUSB0` remoto a partir de uma porta virtual local (por exemplo, executar o Arduino IDE pela internet). Uma issue foi aberta [aqui](https://github.com/richlegrand/bitbang-cli/issues/3).
- **Área de trabalho remota** -- tela por meio de uma faixa de vídeo WebRTC, teclado/mouse pelo canal de dados.
## Licença
MIT -- consulte [LICENSE](https://github.com/richlegrand/bitbang-cli/blob/main/LICENSE).
## Contribuindo
Issues e PRs são bem-vindos.
Receitas são diferentes: elas ficam no [cookbook](https://github.com/richlegrand/bitbang/blob/main/cookbook.md),
no repositório [bitbang](https://github.com/richlegrand/bitbang), porque abrangem
todos os projetos em vez deste. Adicionar uma receita é um PR lá.
Fazê-la ser *listada* é um segundo PR pequeno por projeto cujo README deve exibi-la
-- a lista de [Receitas](#recipes) acima é mantida aqui manualmente. Isso é
deliberado: cada projeto decide quais receitas valem a pena colocar diante de seus
próprios leitores, em vez de todo README crescer com todas as receitas.Descubra as ferramentas mais usadas pela nossa comunidade.
Sem dados de popularidade ainda.