
Établissez un accès distant sécurisé à une machine avec un shell interactif, le transfert de fichiers et un proxy web via WebRTC peer-to-peer chiffré de bout en bout, en utilisant un navigateur ou une CLI, sans redirection de ports ni comptes.
# BitBang CLI
[](https://github.com/richlegrand/bitbang-cli/actions/workflows/tests.yml)

`bitbang` est un multitool d'accès à distance sous forme d'un unique binaire statique. Depuis n'importe quel navigateur : un shell interactif et un navigateur de fichiers pour accéder à la machine distante. Vous pouvez également atteindre les applications web sur le réseau de cette machine. Au-delà du navigateur, il effectue du transfert de ports TCP, de la copie de fichiers et du partage de terminal. Il ne nécessite aucun compte ni configuration -- il fonctionne tout simplement.

Sur la machine que vous souhaitez atteindre :
```
curl -sSfL bitba.ng/install | sh
bitbang serve
```
`serve` affiche une URL. Ouvrez-la dans n'importe quel navigateur et vous obtenez un terminal, un navigateur de fichiers et un proxy vers le réseau de cette machine -- ou atteignez la même machine depuis un autre terminal avec `bitbang connect <url>`, qui ajoute le transfert de ports (`-L`) et la copie de fichiers (`bitbang cp`). La connexion est chiffrée de bout en bout et pair-à-pair ; le serveur `bitba.ng` met les deux extrémités en relation, puis s'efface.
`bitbang` est un unique binaire Go statique. Il fait partie du [projet BitBang](https://github.com/richlegrand/bitbang) ; ce [livre blanc](https://github.com/richlegrand/bitbang/blob/main/whitepaper.md) couvre la conception en profondeur.
## Comparaison
| | ngrok | Tailscale | `bitbang` |
| ------------------------------ | ---------------------- | ------------------------------ | ------------------- |
| Configuration avant la première utilisation | Compte + authtoken | Compte + connexion sur chaque appareil | **Exécuter une seule commande** |
| Pour partager quelque chose, vous exécutez | un serveur web, plus ngrok | leur client sur les deux machines | **`bitbang serve`** |
| Ce qu'obtient un navigateur à l'autre bout | le serveur web que vous exécutiez déjà | rien -- il faut leur client | **un terminal, un navigateur de fichiers et des applications web sur le réseau distant** |
| Chemin des données | leurs serveurs | P2P (repli sur relais) | **P2P (repli sur relais)** |
| Chiffré de bout en bout | Pas par défaut | Oui | **Oui** |
## Recettes rapides
**Atteindre un service à la maison**
- [Monter votre NAS domestique depuis n'importe où (SMB)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#mount-your-home-nas-from-anywhere-smb)
- [Regarder votre bibliothèque multimédia depuis n'importe où (Jellyfin)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-your-media-library-from-anywhere-jellyfin)
- [Utiliser votre propre LLM depuis n'importe où (Ollama, Open WebUI)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#use-your-own-llm-from-anywhere-ollama-open-webui)
- [Consulter vos caméras de sécurité (Frigate)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-security-cameras-frigate)
- [Atteindre votre domotique sans l'exposer (Home Assistant)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-your-home-automation-without-exposing-it-home-assistant)
- [Imprimer sur votre imprimante domestique (IPP, CUPS)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#print-to-your-home-printer-ipp-cups)
**Accéder à une machine**
- [Obtenir un shell sur une machine derrière un NAT](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-on-a-machine-behind-nat)
- [Obtenir un shell depuis votre téléphone](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-from-your-phone)
- [Bureau à distance vers une machine Windows (RDP)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#remote-desktop-into-a-windows-machine-rdp)
- [Atteindre un bureau Linux ou Mac (VNC)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-linux-or-mac-desktop-vnc)
- [SSH vers une machine sans port ouvert (OpenSSH)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#ssh-to-a-machine-with-no-open-port-openssh)
- [Configurer un Raspberry Pi sans écran](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#set-up-a-headless-raspberry-pi)
**Partager avec quelqu'un d'autre**
Le partage consiste simplement à donner à quelqu'un une URL unique ou un QR code qui lui donne accès. Les permissions peuvent être personnalisées et configurées pour expirer en minutes, heures, etc.
- [Partager des fichiers sans les téléverser nulle part](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#share-files-without-uploading-them-anywhere)
- [Montrer votre projet à quelqu'un](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-your-project)
- [Montrer à quelqu'un l'erreur sur laquelle vous êtes bloqué](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-the-error-you-are-stuck-on)
- [Donner à quelqu'un un accès qui expire](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#give-someone-access-that-expires)
- [Vérifier votre session d'agent depuis votre téléphone (Claude Code, tmux)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-agent-session-from-your-phone-claude-code-tmux)
- [Réparer le routeur de quelqu'un d'autre](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#fix-someone-elses-router)
**Développement et appareils**
- [Atteindre une base de données depuis votre machine de développement (Postgres, MySQL)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-database-from-your-dev-machine-postgres-mysql)
- [Synchroniser des appareils qui ne peuvent pas se trouver (Syncthing)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#sync-devices-that-cannot-find-each-other-syncthing)
- [Observer un robot depuis un navigateur (ROS, Foxglove)](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-a-robot-from-a-browser-ros-foxglove)
**Techniques**
- [Ce qu'expose un listener de transfert](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#what-a-forwarding-listener-exposes)
- [Permettre à d'autres machines de votre LAN d'utiliser un transfert](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#let-other-machines-on-your-lan-use-a-forward)
- [Connu pour ne pas fonctionner](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#known-not-to-work)
## Utiliser `bitbang`
Chaque connexion a deux extrémités : un **listener** (`bitbang serve`, exécuté sur la machine à atteindre) et un **connector** (un navigateur, ou la CLI `bitbang`, sur la machine qui effectue la connexion). Une seule URL de listener sert les deux types de connector.
### Le 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
```
Chacun affiche un QR code, une URL et un code d'appairage. Le mode détermine ce que l'écouteur peut faire du tout : `serve shell` n'a aucun transfert à accorder, et un écouteur en transfert seul ne démarre jamais de shell, il n'y a donc rien vers quoi escalader.
Un comportement par défaut qu'il vaut la peine de connaître : **le transfert et le proxy atteignent n'importe quel host:port que l'écouteur peut atteindre**, pas seulement celui que vous aviez en tête, donc un lien distribué pour une base de données atteint aussi le reste de ce réseau. Nommer les cibles après le mot le restreint -- `forward db.internal:5432` atteint celle-ci et rien d'autre.
### Partager une session en cours : `bitbang share`
`serve shell` démarre un nouveau shell. `share` publie une session tmux déjà en cours d'exécution :
```
bitbang share # publish the current tmux session
bitbang share --read-only # publish without a control URL
bitbang share status|stop|rotate
```
La commande rend la main après la publication, donc `Ctrl-Z`, `bitbang share`, `fg`
fonctionne pour une tâche déjà en cours. L'hébergement nécessite tmux 3.2+ sous Unix ou
WSL. Les clients Windows natifs peuvent ouvrir les URL mais ne peuvent pas héberger un partage.
Par défaut, la commande affiche deux URL porteuses :
- L'**URL de contrôle** peut saisir avec la même autorité que le clavier local.
Un seul contrôleur peut se connecter à la fois.
- L'**URL de visualisation** est en lecture seule. Les entrées sont supprimées avant d'atteindre tmux, et
jusqu'à `--max-viewers` spectateurs peuvent se connecter simultanément (16 par défaut).
`--read-only` omet entièrement l'identifiant de contrôle. Les limites de spectateurs et de contrôleurs
sont maintenues pendant toute la durée de vie de chaque connexion, même avant qu'elle n'ouvre un shell.
Les partages s'exécutent jusqu'à leur arrêt par défaut ; `--ttl` définit une durée de vie (par ex. `--ttl 1h`).
Les URL de partage sont éphémères et ne sont jamais enregistrées dans `devices.json`. `share stop`,
l'expiration du TTL, ou la suppression de la session source déconnecte les pairs distants sans
arrêter la session source.
Relancer `bitbang share` réaffiche les URL du partage en cours. Si vous
passez un indicateur qui ne correspond pas à ce qui est en cours (par exemple `--read-only`
contre un partage qui possède une URL de contrôle), il le signale plutôt que
de renvoyer les anciennes URL ; `bitbang share rotate` remplace le partage
par un qui utilise les nouveaux indicateurs.
Un worker en arrière-plan s'exécute dans une session de gestion tmux `_bbshare_*` détachée,
il n'y a donc ni démon ni fichier PID à gérer.
Le partage ne modifie aucune option tmux. Avec le `window-size latest` par défaut de tmux, la
fenêtre suit le client actif en lecture-écriture ; un spectateur seul fournit toujours la
seule taille disponible. Si `window-size` a été surchargé, `share` le signale
mais ne modifie pas la configuration de l'utilisateur.
### Distribuer un accès limité : `bitbang link`
Un seul listener, une seule URL, et autant de **liens d'accès** que nécessaire. Chacun est un
code séparé sur cette même URL, accordant un sous-ensemble de ce que le listener offre
et expirant éventuellement à une heure fixe :
```
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
```
Une entrée est une ligne de JSON dans `~/.bitbang/bitbang/links.json`. Écrivez-en une sans code, rechargez l'écouteur depuis sa console, et il en génère une :
```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` est le propre code de l'identité et accorde tout ce que le listener sert ; envoyez
l'un des autres à la place. La console accepte soit le libellé, soit le numéro à côté,
donc `rm 2` et `rm ben` font la même chose.
Un `grant` s'écrit avec les mots que prend `serve`, et il ne peut que restreindre ce que le
listener sert déjà. Cela signifie qu'un lien n'est pas limité au choix des capacités :
il peut nommer un sous-répertoire du dossier partagé, un sous-ensemble des cibles de transfert, ou
une seule commande pour `shell`. Omettez `grant` et le lien accorde tout ce que fait le listener.
Demandez quelque chose hors de portée du listener et la console le refuse avec le même message
que `serve` vous donnerait.
Le libellé est ce qui identifie un lien, pas ses termes, donc deux personnes peuvent détenir des liens
avec des grants et une expiration identiques et vous pouvez toujours en révoquer un sans toucher
à l'autre.
La révocation et l'expiration atteignent les sessions déjà ouvertes : la connexion se ferme
et le détenteur est informé de la raison, plutôt que de rester silencieux. Et un code expiré est
retiré plutôt que mis en pause -- renouveler une entrée en génère une nouvelle, donc l'URL que vous
avez déjà envoyée reste morte.
### Où BitBang conserve ses fichiers
Tout ce que BitBang stocke sur lui-même vit dans un seul répertoire : la paire de clés d'identité
qui fixe votre URL, la table des liens, la table des appareils enregistrés que lisent `connect`
et `cp`, et l'état des partages. Par défaut, c'est `~/.bitbang`.
Un service ne peut souvent pas utiliser `~`. `-home` définit le répertoire, et `BITBANG_HOME`
fait de même sans répéter le drapeau à chaque commande :
```
bitbang serve shell -home /var/lib/bitbang
BITBANG_HOME=/var/lib/bitbang bitbang link ls
```
Le flag est présent sur chaque commande et pas seulement sur `serve`, car le répertoire n'appartient pas à serve — l'oublier une fois sur `bitbang link` modifierait une table différente.
L'ordre complet, la première correspondance l'emporte :
| Défini | Répertoire utilisé |
|---|---|
| `-home <dir>` | exactement celui-ci |
| `$BITBANG_HOME` | exactement celui-ci |
| `$STATE_DIRECTORY` | exactement celui-ci — systemd le définit à partir de `StateDirectory=`, donc une unité n'a besoin de rien d'autre |
| `$XDG_STATE_HOME` | `$XDG_STATE_HOME/bitbang` |
| `$HOME` | `$HOME/.bitbang` |
| aucun d'entre eux | rien : BitBang s'arrête et le signale |
Les trois premiers désignent le répertoire lui-même ; les deux derniers désignent un parent dont il dépend.
Cette dernière ligne compte sur une machine où l'utilisateur du service n'a pas de home. Les versions précédentes se rabattaient sur le répertoire de travail, si bien qu'un listener démarré sans `HOME` écrivait sa paire de clés là où il se trouvait au démarrage — `/` pour un script d'init. Il refuse désormais plutôt que de placer une clé privée dans un emplacement que personne n'a choisi.
Le listener nomme le répertoire au démarrage, vous n'avez donc jamais à déterminer lequel de ces cas l'emporte :
```
Home: /home/you/.bitbang
Home: /var/lib/bitbang (STATE_DIRECTORY)
```
Ainsi, une unité systemd ne nécessite aucune configuration spécifique à BitBang pour cela :
```ini
[Service]
StateDirectory=bitbang
ExecStart=/usr/local/bin/bitbang serve shell
```
### Appairage avec un code à 6 chiffres
Lorsque vous ne pouvez pas coller une URL ni scanner un QR code, par exemple au téléphone ou à portée de voix, `bitbang serve` affiche également un court **code d'appairage**. L'autre partie ouvre `bitba.ng/<code>` (ou exécute `bitbang connect <code>`), son écran affiche un second nombre à 6 chiffres, et elle vous lit *celui-là*. Vous le saisissez pour approuver. Un attaquant de type machine-in-the-middle ne peut pas faire correspondre les deux nombres, et l'appairage enregistre les identifiants de connexion de l'appareil pour la prochaine fois, par ex. `bitbang connect nas1`. Si vous connaissez [Magic Wormhole](https://github.com/magic-wormhole/magic-wormhole), la forme est similaire -- un code énoncé oralement qui présente deux machines de manière sécurisée.

### Apportez votre propre TURN
La plupart des connexions passent directement en pair-à-pair. Lorsque les deux extrémités se trouvent derrière un NAT qui
ne permet pas le hole-punching, le trafic a besoin d'un relais, et par défaut c'est le nôtre. `-ice-servers`
indique à l'écouteur d'utiliser le vôtre à la place :
```
bitbang serve -ice-servers ~/turn.json
```
Le listener transmet la configuration au serveur de signalisation lors de l'enregistrement, et le serveur la transmet à quiconque se connecte -- ainsi les deux extrémités utilisent votre relais et le nôtre n'est jamais impliqué. N'importe quel coturn, ou un fournisseur hébergé comme Cloudflare ou Twilio, fonctionne.
Le fichier est au format JSON, selon l'une de ces trois formes que votre fournisseur vous a fournie :
```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` accepte une chaîne ou une liste ; `username` et `credential` concernent TURN et peuvent être omis d'une entrée STUN uniquement. Le chemin peut être absolu, relatif ou enraciné sur `~`. Un fichier qui ne se parse pas arrête le listener au démarrage plutôt que de basculer silencieusement.
Si une session finit par être relayée sans qu'on l'ait demandé, `bitbang connect` le signale plutôt que de vous laisser vous demander pourquoi cela semble lent. Le listener le journalise dans tous les cas (`via RELAY`), et `-relay` / `-norelay` forcent la question dans un sens ou dans l'autre lorsque vous diagnostiquez un chemin.
Il vaut la peine de le préciser : il s'agit de qui transporte les octets, pas de qui peut les lire. Un relais ne voit jamais que du chiffré DTLS, le nôtre inclus. Lancez le vôtre lorsque vous avez besoin de plus de TURN que ce que nous pouvons fournir (nous limitons actuellement la durée).
### Se connecter depuis un navigateur
Ouvrez l'URL. Selon ce qui est servi, vous obtenez :
- **Shell** -- un terminal complet dans la page (couleurs, redimensionnement, copier/coller).
- **Files** -- parcourir, prévisualiser, télécharger et envoyer des fichiers.
- **Proxy** -- saisissez une adresse LAN (`nas.local`, `192.168.1.10:8080`, `localhost:3000/admin`) et utilisez l'application comme si vous étiez en local. Les connexions, les cookies, les envois de fichiers et le streaming fonctionnent tous.
<!-- TODO: per-feature demos -->
<!-- Remote shell in a browser tab -->
<!-- Streaming Jellyfin through the proxy -->
### Se connecter depuis la 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` ne transmet que le **TCP**, comme `ssh -L`. `-L` se lie à `127.0.0.1` sauf si vous passez
`-g`, ce qui rend le port transféré accessible depuis votre réseau local -- et
quiconque l'atteint obtient ce que le tunnel atteint, sans
identifiant BitBang devant lui.
L'écouteur nécessite `bitbang serve forward` ou `bitbang serve`. Par défaut, un
lien `forward` atteint **n'importe quel hôte:port que l'écouteur peut atteindre**, pas seulement
celui que vous aviez en tête, donc un lien distribué pour une base de données atteint aussi le reste
de ce réseau. Restreignez-le en nommant ce qu'il peut atteindre :
```
bitbang serve forward db.internal:5432 # this link reaches one service
```
Chaque connexion ou appairage réussi est enregistré dans `~/.bitbang/devices.json`, de sorte qu'ensuite un nom court suffit : `bitbang connect nas1`.
## Prise en charge des plateformes
Un binaire par plateforme, aucune dépendance d'exécution. Tout fonctionne
partout, sauf les deux lignes signalées ci-dessous.
| | Linux | macOS | Windows |
| ---------------------------------------- | :---: | :---: | :-----: |
| Shell, fichiers, proxy (`bitbang serve`) | oui | oui | oui |
| Redirection TCP (`-L`) | oui | oui | oui |
| Liens d'accès -- octroi, expiration, révocation | oui | oui | oui |
| Apport de votre propre TURN | oui | oui | oui |
| Appairage avec un code à 6 chiffres | oui | oui | oui |
| La console d'écoute (Entrée) | oui | oui | oui |
| `bitbang connect`, `bitbang cp` | oui | oui | oui |
| Visualisation d'une session partagée | oui | oui | oui |
| **Hébergement d'un partage** (`bitbang share`) | oui | oui | non * |
| **Redimensionnement du terminal pendant la connexion** | oui | oui | non ** |
\* `bitbang share` publie une session tmux, donc en héberger une nécessite tmux --
Linux, macOS ou WSL. Windows natif peut toujours ouvrir des URL de partage avec
`bitbang connect`.
\*\* Un connecteur Windows ne remarque pas le redimensionnement de son terminal, donc le
shell distant conserve la taille avec laquelle il a démarré jusqu'à ce que vous vous reconnectiez. Unix
obtient cela via `SIGWINCH`, dont Windows n'a pas d'équivalent.
## Sécurité
- **Identité auto-certifiante.** Au premier lancement, `bitbang` génère une paire de clés RSA sous `~/.bitbang/<program>/` ; l'UID de l'appareil est dérivé de la clé publique, donc usurper l'identité d'un appareil revient à trouver une seconde préimage de son UID.
- **Le secret ne touche jamais le serveur.** Le code d'accès réside dans le fragment d'URL (`#…`), que les navigateurs n'envoient jamais -- `bitba.ng` court-circuite la connexion sans jamais voir l'identifiant qui l'autorise.
- **Chiffrement de bout en bout.** Tout le trafic passe par DTLS de WebRTC. Le serveur de signalisation ne voit que la clé publique, l'UID dérivé et les métadonnées de connexion -- jamais vos données. Un relais TURN, si l'un est nécessaire, ne voit que du texte chiffré.
- **Appairage vérifié.** Le numéro lu à voix haute lors de l'appairage par code est une chaîne d'authentification courte (SAS), calculée indépendamment aux deux extrémités à partir des empreintes DTLS négociées et de deux nonces engagés -- un attaquant de type machine-au-milieu, dont les empreintes diffèrent nécessairement, ne peut pas faire correspondre les deux numéros.
- **L'URL est un identifiant porteur.** Quiconque la possède obtient ce que vous avez choisi de servir -- un shell, si vous avez lancé `serve shell`. Partagez-la en conséquence.
- **PIN facultatif** (`--pin`) pour les configurations permanentes ou sans interface, et **mode jetable** (`-ephemeral`) pour une identité neuve à chaque exécution.
- **Ce que le serveur voit encore.** Pas rien. Il court-circuite la présentation, donc
il observe les adresses IP des deux extrémités, le moment où elles se connectent et le volume de leurs
échanges. Le chiffrement de bout en bout le tient à l'écart de vos données, pas des
métadonnées qui les entourent -- *confiance minimale* est une description plus juste que
*sans confiance*.
- **Un navigateur fait confiance à la page qu'il a chargée.** Le client navigateur est du JavaScript
servi par le serveur de signalisation, donc ouvrir une URL signifie faire confiance à ce serveur
pour servir du code honnête. `bitbang connect` n'a pas une telle dépendance : c'est un
binaire que vous avez installé et vérifié par somme de contrôle. Si cette distinction compte pour vous,
connectez-vous avec le CLI.
La manière dont les deux extrémités s'authentifient mutuellement, afin que le serveur de signalisation ne puisse pas
s'insérer dans la connexion, est couverte en détail ici : [*Trustless Signaling: Authentication Without a Central Authority*](https://github.com/richlegrand/bitbang/blob/main/trustless-signaling.md).
## Pourquoi ?
- **Rien à ouvrir ni à configurer.** Fonctionne derrière un NAT, un CGNAT ou un réseau verrouillé -- aucune modification de routeur, aucun VPN, aucun démon de tunnel.
- **Rien à installer du côté qui se connecte.** Un navigateur suffit. Une CLI est disponible lorsque vous voulez scripter, utiliser des pipes et copier des fichiers.
- **Privé par conception.** Le trafic est WebRTC/DTLS, en pair-à-pair. Le serveur de signalisation ne le voit jamais ; si un chemin direct n'est pas possible, un relais TURN ne transporte que du texte chiffré.
- **Pas de compte, pas de télémétrie.**
### Pourquoi ne pas simplement utiliser SSH ? Ou Tailscale ?
Réponse courte : pour une machine à laquelle vous pouvez déjà vous connecter en SSH, ou pour un parc de vos propres appareils sur lesquels vous pouvez installer quelque chose, continuez d'utiliser ce que vous avez. `bitbang` est fait pour les cas où l'extrémité distante est une personne plutôt qu'un appareil, ou lorsque vous ne pouvez rien installer là où vous vous trouvez. Ces deux questions sont traitées en détail dans la **[FAQ](https://github.com/richlegrand/bitbang-cli/blob/main/FAQ.md)**.
## Installation
```
curl -sSfL bitba.ng/install | sh
```
Linux et macOS. Détecte votre OS et votre architecture (`amd64`, `arm64` et `armv7` sous Linux), télécharge le binaire depuis la dernière [version GitHub](https://github.com/richlegrand/bitbang-cli/releases), vérifie son SHA-256 par rapport au fichier `checksums.txt` de la version, et l'installe dans `~/.local/bin/bitbang`.
Les builds Windows sont publiés sous les noms `bitbang-windows-amd64.exe` et
`bitbang-windows-arm64.exe`. Téléchargez le binaire approprié depuis les Releases,
renommez-le en `bitbang.exe` et placez-le dans votre `PATH`.
**Compiler depuis les sources :** voir [ci-dessous](#building-from-source).
**macOS et Gatekeeper.** L'installation en une ligne ci-dessus n'est pas concernée : `curl` ne
définit pas l'attribut `com.apple.quarantine`, donc le binaire qu'il récupère s'exécute
normalement. Si vous téléchargez plutôt `bitbang-darwin-arm64` depuis la page Releases
dans un navigateur, macOS le met en quarantaine et refuse de l'ouvrir, car les binaires
de la version ne sont pas notariés. Supprimez la quarantaine avec l'une ou l'autre de ces commandes :
```
xattr -d com.apple.quarantine ./bitbang-darwin-arm64
```
ou faites un clic droit sur le fichier dans le Finder et choisissez Ouvrir, ce qui propose une
dérogation unique. Vous pouvez également compiler depuis les sources, ce qui ne met jamais en quarantaine.
**Windows et SmartScreen.** La même chose se produit sous Windows, pour la même
raison. Un téléchargement via navigateur attache la Mark-of-the-Web, donc le premier lancement affiche
*« Windows a protégé votre PC »* -- choisissez **Plus d'infos**, puis **Exécuter quand même**. Les
binaires de version ne sont pas signés numériquement, c'est donc attendu plutôt qu'un signe
que quelque chose ne va pas. Récupérer le `.exe` avec `curl` ou `Invoke-WebRequest` de PowerShell
ne l'attache pas, et compiler depuis les sources non plus.
### Options d'installation
Épinglez une version, changez l'emplacement, ou lisez le script avant de l'exécuter :
```
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
```
Les tags de release n'ont pas de préfixe `v` (`0.5.0`, pas `v0.5.0`).
### Fonctionnement de l'URL d'installation
`bitba.ng/install` est une redirection, pas un script hébergé. La chaîne :
1. `curl` accède à `https://bitba.ng/install`, qui renvoie une 302 vers [`install.sh`](https://github.com/richlegrand/bitbang-cli/blob/main/install.sh) dans ce dépôt (sur `main`).
2. Le script s'exécute dans votre shell, détecte l'OS et l'architecture, puis télécharge le binaire depuis `https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>`.
3. Il récupère `checksums.txt` depuis la même release et vérifie le SHA-256 du binaire.
4. Il installe dans `~/.local/bin` (chemin modifiable).
Le script d'installation réside dans ce dépôt, à côté du code qu'il installe -- vous pouvez donc l'examiner en même temps que le binaire, et l'hôte canonique bitba.ng ne possède que l'URL courte. Les auto-hébergeurs peuvent pointer le `/install` de leur propre hôte vers le script qu'ils distribuent : la variable d'environnement `INSTALL_URL` du serveur de signalisation contrôle la cible de la redirection (vide → 404).
## Référence des commandes
Chaque sous-commande et option se trouve dans **[CLI.md](https://github.com/richlegrand/bitbang-cli/blob/main/CLI.md)**, et `bitbang <command>
--help` affiche la même chose dans le terminal.
## Compilation depuis les sources
Nécessite Go 1.25+. Go pur, lié statiquement (`CGO_ENABLED=0`) -- compilation croisée triviale, aucune dépendance à l'exécution.
```
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/
```
Depuis l'invite de commandes Windows :
```bat
go build -o bitbang.exe .\cmd\bitbang
go test .\...
run_tests.cmd unit
```
Les commandes shell, le partage de fichiers, le proxy et le client CLI sont pris en charge sous
Windows. Les shells interactifs du navigateur et de la CLI utilisent Windows ConPTY, y compris
l'écho des entrées du terminal, l'édition de ligne, la sortie VT et les événements de redimensionnement. ConPTY nécessite
Windows 10 version 1809 ou Windows Server 2019 ou ultérieur.
## Diagrammes
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/47068/d68fcddad62ab84f11a549906a2b5abf2330fb25f39b3c1a1266eac7257a080d.png" alt="shell CLI bitbang et partage de fichiers" width="760">
<img src="https://assets.kitploit.com/production/public/readmes/47068/55bb6866c22504a6434e3dee8cb998e747cd73cb9d0bfa5e0bc0ede7b90ce262.png" alt="fonctionnement du proxy CLI bitbang" width="720">
</p>
## Feuille de route
Disponible aujourd'hui : **shell, fichiers et proxy**, accessibles depuis le navigateur ou la CLI, ainsi que le **transfert de ports TCP**, la copie de fichiers de style scp, l'**appairage ad hoc** avec une table d'appareils enregistrée, le **partage de terminal** (`bitbang share`) et les **liens d'accès** (`bitbang link`) qui restreignent et font expirer ce qu'une URL accorde. Conçus et en cours de développement :
- **Pont série** -- piloter un `/dev/ttyUSB0` distant depuis un port virtuel local (par ex. exécuter l'IDE Arduino via Internet). Une issue a été ouverte [ici](https://github.com/richlegrand/bitbang-cli/issues/3).
- **Bureau à distance** -- écran via une piste vidéo WebRTC, clavier/souris via le canal de données.
## Licence
MIT -- voir [LICENSE](https://github.com/richlegrand/bitbang-cli/blob/main/LICENSE).
## Contribution
Les issues et les PR sont les bienvenues.
Les recettes sont différentes : elles résident dans le [cookbook](https://github.com/richlegrand/bitbang/blob/main/cookbook.md),
dans le dépôt [bitbang](https://github.com/richlegrand/bitbang), car elles couvrent
---
[Read more](https://github.com/richlegrand/bitbang-cli)