bitbang 0.1.13

Connect browsers to devices via WebRTC

BitBang

Access your local web server from anywhere -- no account, no subscription, no cloud in the middle. BitBang uses WebRTC to connect browsers directly to your device, peer-to-peer.

Quick demo

Install:

pip install bitbang

Quick test:

bitbang-fileshare ~/Downloads

This prints a URL and QR code. Anyone with the link can browse and download files directly from your machine, or they can upload files to the specified directory. Note, you can verify it works outside your local network, by scanning the QR code from a phone on cellular (turn off WiFi).

Flask / FastAPI integration (or any WSGI/ASGI web framework)

# Flask 
from bitbang import BitBangWSGI
...
app = Flask(__name__)
adapter = BitBangWSGI(app)
adapter.run()  # Prints QR code and public URL

# FastAPI 
from bitbang import BitBangASGI
...
app = FastAPI()
adapter = BitBangASGI(app)
adapter.run() # Prints QR code and public URL

Comparison

	ngrok	Cloudflare Tunnel	Tailscale	BitBang
Account required	Yes	Yes	Yes	No
Free tunnels	1	Unlimited	Unlimited	Unlimited
Data path	Their servers	Their servers	P2P	P2P
Viewer needs install	No	No	Yes	No
Configuration	CLI flags	Config file + DNS	Dashboard	None

BitBang's data path is direct between peers. The signaling server brokers the initial connection, then steps aside.

---

Fileshare

Share files without uploading them to a third-party service:

bitbang-fileshare big_sourcetree.tar.gz   # Share a single file
bitbang-fileshare ~/Documents/project     # Share a directory (uploads enabled)

Files transfer directly from your machine to the recipient. The recipient can also upload files if a directory is specified.

Webcam

The webcam app streams video to your browser using WebRTC media channels. It can be used as an easy-to-setup monitoring/security camera using your laptop, for example.

bitbang-webcam 

Examples

The examples/ directory contains two simple examples which show how to integrate BitBang into your current Python web frameworks:

cd examples/simple_fastapi && python3 app.py
cd examples/simple_flask && python3 app.py

---

Background

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

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, and ngrok for web apps -- among others. 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 connects a browser directly to any machine on your local network, from anywhere on the Internet. No cloud intermediary, no account, no third party in the middle. It uses a novel application of the peer-to-peer technology WebRTC.

WebRTC

WebRTC is the behind-the-scenes technology that makes Zoom and Google Meet video conferencing possible. WebRTC offers the highest bandwidth and lowest latency possible, which is nice when you're streaming live video, or practically anything else. It's mature, well-tested, and has ubiquitous support across all browsers. In addition to delivering low-latency media, it can also deliver raw data over "data channels", which is what BitBang uses.

---

How it works

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

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

Signaling server

The signaling server source is available here. It:

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

After the P2P connection is established, the signaling server is not involved.

Security

WebRTC mandates encryption:

• Data channels: DTLS 1.2+
• Media streams: SRTP
• Signaling: HTTPS and WSS

Furthermore, each BitBang "device" generates an RSA keypair. The public key hash becomes its unique ID, which is used in its BitBang public URL. The signaling server challenge-verifies key ownership before accepting connections.

Roadmap

BitBangProxy -- A standalone binary that proxies any server on the local network. Run it once; the target is specified in the URL at browse-time.

https://bitba.ng/<proxy-id>/192.168.1.10:80
https://bitba.ng/<proxy-id>/nas.local
https://bitba.ng/<proxy-id>/octopi.local:5000

ESP32 support -- Native BitBang for microcontrollers, including video streaming and OTA updates. It's an IoT network with no account set-up, subscription, etc.

---

License

MIT

Contributing

Issues and pull requests are welcome.