bitbang README

The project's README from github.com/richlegrand/bitbang. As one markdown file: README.md.

BitBang

BitBang turns any machine into a URL.

Run BitBang, get a URL, and open it in any browser -- you're connected to the machine, peer-to-peer and end-to-end encrypted. There's no account, no port forwarding, and nothing to install on the connecting side.

This repository is the entry point to the BitBang project. The code lives in the repos below.

Try it (30 seconds)

On the machine you want to reach (Linux; other platforms are coming):

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

serve prints a URL. Open it in any browser for a terminal, a file browser, and a proxy to that machine's network. Full documentation, pairing, and the CLI client: bitbang-cli.

The repositories

bitbang-cli -- start here. Turns any machine into a URL: remote shell, file access, and web-app proxying, from a browser or another terminal. For you if you want remote access to a machine, now.

Octoprint-BitBang -- turns your 3D printer into a URL: the full OctoPrint UI, including hardware-encoded H.264 video from the printer's camera. For you if you have a 3D printer.

bitbang-python -- turns any Python program into a URL (pip install bitbang): wraps any WSGI or ASGI app (Flask, FastAPI, Quart), with live video streaming. For you if you're building something.

bitbang-server -- the machinery behind the URLs: the signaling server and browser runtime. It powers bitba.ng, and you can self-host it -- the whole stack, under your control. For you if you trust no one, which around here is considered a feature.

Read more

Why BitBang is needed

The Internet is often thought of as a fully connected network -- every machine accessible from every other machine. But there are rules governing accessibility...

Rules of Internet Accessibility

  1. Machines on the Internet are accessible by other machines on the Internet -- and by machines on your local network.
  2. Machines on your local network are only accessible by other machines on your local network.

Because of rule 2, machines on your local network aren't reachable from outside -- nor are the resources they hold: files, cameras, sensors, compute, or the web app you're currently developing. Cloud services exist to fill this gap: Dropbox for files, AWS IoT for sensors, Tailscale for compute, ngrok for web apps. These services apply rule 1, but each comes with the friction of account creation, fees, and your data living on someone else's server.

BitBang takes a different path: devices connect directly to browsers, peer-to-peer, with the server reduced to a brief introduction it can neither read nor tamper with. For a feature-by-feature comparison with ngrok, Cloudflare Tunnel, and Tailscale, see the bitbang-cli README.

How it works

Browsers normally connect to web servers over a TCP socket. BitBang replaces this with a WebRTC data channel.

BitBang block diagram

The signaling server (bitba.ng) brokers the WebRTC handshake, then has no further involvement and never sees application data.

WebRTC?

WebRTC is the technology behind Zoom and Google Meet. It was designed for real-time media -- sub-second latency, high bandwidth -- and it's mature, well-tested, and built into every major browser. Alongside media it carries raw data over "data channels," which is what BitBang uses to proxy HTTP and WebSockets. WebRTC is also notoriously unpleasant to use directly: signaling, SDP, ICE, DTLS fingerprints, TURN. Burying that is most of what BitBang does. You get an address, not a protocol project.

Signaling server

The signaling server (source) does four things:

  1. Serves the BitBang browser runtime
  2. Authenticates connecting devices via RSA challenge
  3. Maintains WebSocket connections to active devices
  4. Brokers ICE candidate and SDP exchange between browsers and devices

After the P2P connection is established, the signaling server is not involved. We provide one at https://bitba.ng; it mostly brokers connections, so its resource needs are small -- and you can run your own.

Security

WebRTC mandates encryption:

Each BitBang device generates an RSA keypair. The public key hash becomes its unique 128-bit ID, used in its BitBang URL. A 64-bit access code rides in the URL fragment (after #), which browsers never send to a server -- so the signaling server can route connections but cannot initiate them. How the two ends authenticate each other without trusting the server, and exactly where that guarantee's boundary lies, is covered in Trustless Signaling.

Origin

In 2010, I gave a Google Tech Talk with Illah Nourbakhsh of Carnegie Mellon on TeRK (Telepresence Robot Kit), a Google- and Intel-funded project to make educational robotics accessible. Our conclusion had little to do with robots: the internet is broken for devices. NATs and firewalls make every device behind a home router invisible from the outside. Google had recently open-sourced libjingle -- the P2P engine behind Google Talk -- and we wanted to use it for zero-config device connectivity. But it was a C++ library tied to XMPP, and we felt strongly the technology should be browser-friendly. That was too big a problem for our resources.

In the years that followed, connected devices became "IoT" and converged on a single pattern: Platform-as-a-Service. Your device talks to a cloud, your browser talks to the same cloud, and they meet in the middle -- accounts, subscriptions, and your data on someone else's server. Meanwhile WebRTC, libjingle's direct descendant, quietly shipped in every major browser. But it was built for video calls, and by the time it arrived, IoT had already settled into its cloud pattern -- peer-to-peer never entered the picture. BitBang is what happens when it does: devices talk directly to browsers, with no cloud in the data path and no account required. BitBang was built for Goby, a tiny telepresence robot that launched on Kickstarter in 2025 -- the spiritual descendant of TeRK, realized with the technology we had wished for fifteen years earlier. We promised to open-source the networking stack that made it possible. BitBang is that stack.

License

MIT, across all repositories.

Contributing

Issues and PRs are welcome.

bitbang (richlegrand/bitbang)

Searching Database…

184 ·GitHub
Bitbang
Что это такое?BitBang превращает любую машину в ссылку: запустите её на устройстве, откройте ссылку в любом браузере — и вы подключитесь к этой машине напрямую, peer-to-peer, со сквозным шифрованием. Не нужен ни аккаунт, ни проброс портов, ни установка чего-либо на стороне, с которой вы подключаетесь.
Это облачный сервис, в котором нужно регистрироваться, или программа, которую я запускаю сам?Это открытый (open-source, лицензия MIT) софт, который вы запускаете сами, а не сервис с аккаунтами. Этот репозиторий — входная точка целого набора подрепозиториев; публичный signaling-сервер доступен на bitba.ng, но весь стек можно развернуть у себя и полностью контролировать.
Как подключиться к одной из своих машин?На машине, к которой хотите подключиться (сейчас это Linux), установите bitbang-cli и запустите serve — она выведет BitBang-ссылку. Открыв её в браузере, вы получите терминал, файловый менеджер и прокси к сети этой машины.
Что нужно на устройстве, с которого я подключаюсь?Только современный браузер — WebRTC встроен в каждый крупный браузер, поэтому на подключающейся стороне ничего устанавливать не нужно.
Есть ли текущие ограничения, о которых стоит знать?Сейчас поддержка на стороне устройства есть только для Linux; в README сказано, что другие платформы в планах. Точные границы гарантии отсутствия доверенного сервера описаны отдельно в статье Trustless Signaling.
Где это работает?Пока на стороне устройства — Linux; подключаться можно из любого крупного браузера на любой ОС, потому что на подключающейся стороне ничего не ставится.
Могу ли я поднять серверную часть сам?Да — signaling-сервер можно развернуть у себя, и он в основном только сводит соединения, так что ресурсов требует немного. Можно запустить весь стек целиком, не полагаясь на bitba.ng.
Мой трафик идёт через ваш сервер?Нет — signaling-сервер лишь помогает установить WebRTC-соединение (handshake) и после этого больше не участвует, никогда не видя данных приложений. Каналы данных защищены DTLS 1.2+, медиапотоки — SRTP, а код доступа находится в URL-фрагменте, который браузеры никогда не отправляют на сервер.
Чем это отличается от ngrok или Tailscale?Эти облачные сервисы преодолевают проблему NAT, но требуют создания аккаунта, платных тарифов и размещения ваших данных на чужом сервере. BitBang соединяет устройство напрямую с вашим браузером, peer-to-peer; сервер только знакомит стороны и не может ни читать трафик, ни вмешиваться в него. Поразрофильное сравнение с ngrok, Cloudflare Tunnel и Tailscale есть в README bitbang-cli.
Если кто-то узнает мою ссылку, он сможет подключиться к моей машине?Нет. Каждое устройство генерирует пару ключей RSA, хеш открытого ключа которого становится его 128-битным ID, а 64-битный код доступа находится в URL-фрагменте после # — браузеры никогда не отправляют его на сервер. Поэтому signaling-сервер может маршрутизировать соединения, но не может инициировать их; документ Trustless Signaling подробно описывает, где проходят границы этой гарантии.
Зачем автор это создал?Проект вырос из TeRK — образовательного робототехнического проекта 2010 года, который пришёл к выводу, что интернет сломан для устройств за NAT. Позже WebRTC появился во всех браузерах, но разрабатывался для видеозвонков, поэтому peer-to-peer так и не вошёл в картину интернета вещей. BitBang — это открытый сетевой стек, стоящий за Goby, крошечным телеприсутственным роботом, запущенным на Kickstarter в 2025 году.
What are similar projects?tailcat, dsh-remote-web-gateway, MeshLAN, nebula, dsh-bridge, snapdrop, dashbeam, xpra
Which topics is it in?nat-traversal, 3d-printing, end-to-end-encryption, remote-control, remote-access, file-sharing, video-streaming, webrtc, tunnel, p2p, robotics, iot
Creator
richlegrand
Size
0.5 MB
Stars
184
Updated
CommitOct 02
Age
5mo
Commits · 90 Days