bitbang-python
Turns your local Python web app into a URL you can open from anywhere.
bitbang wraps a WSGI or ASGI app (Flask, FastAPI, Quart) and prints a URL and QR code. Open the URL in any browser and you're connected to the app -- peer-to-peer, end-to-end encrypted, with no account, no port forwarding.
This is the Python implementation of BitBang. For remote access to a whole machine (shell, files, proxy) without writing code, see bitbang-cli.
Install
pip install bitbang # Linux / macOS
python -m pip install bitbang # Windows (or any platform)
Quick test
bitbang-fileshare ~/Downloads # Linux / macOS
python -m bitbang fileshare ~/Downloads # Windows (or any platform)
This prints a URL and QR code. Anyone with the link can browse and download files directly from your machine, or upload files to the shared directory. To verify it works outside your local network, scan the QR code from a phone on cellular (turn off WiFi).
Flask / FastAPI integration (or any WSGI / ASGI framework)
Take an existing app and give it a URL:
# 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
The examples/ directory contains a minimal version of each:
cd examples/simple_fastapi && python3 app.py
cd examples/simple_flask && python3 app.py
Bundled apps
Fileshare shares local files without uploading them to a third-party service. Files transfer directly from your machine to the recipient, and the recipient can upload files back. It's also intended as an example of a simple BitBang application -- it's a straightforward Flask app.
bitbang-fileshare big_sourcetree.tar.gz # Share a single file
bitbang-fileshare ~/Documents/project # Share a directory (uploads enabled)
python -m bitbang fileshare c:\ide\files # Windows
Webcam streams video from your webcam to a browser over WebRTC media channels -- an easy-to-set-up monitoring camera using a laptop, for example.
bitbang-webcam # Linux / macOS
python -m bitbang webcam # Windows (or any platform)
Python API
These options are available from the BitBangWSGI constructor (same options for BitBangASGI):
adapter = BitBangWSGI(app,
program_name='BitBang', # Identity name, shows in browser title
server='bitba.ng', # Signaling server (default: bitba.ng)
ephemeral=False, # Use a temporary identity (not saved to disk)
identity_path=None, # Use a specific identity file
regenerate=False, # Delete and regenerate identity
debug=False, # Verbose logging + browser debug UI (?debug)
pin=None, # PIN string to protect access
pin_callback=None, # Function(path, pin) -> bool for custom auth
ice_servers=None, # Custom TURN server config
)
If your app uses argparse, add_bitbang_args and bitbang_kwargs wire up the standard CLI flags:
from bitbang.adapter import BitBangWSGI, add_bitbang_args, bitbang_kwargs
parser = argparse.ArgumentParser()
parser.add_argument('path')
add_bitbang_args(parser)
args = parser.parse_args()
adapter = BitBangWSGI(app, **bitbang_kwargs(args, program_name='myapp'))
These options appear on the command line as:
--ephemeral Use a temporary identity
--identity PATH Use a specific identity file
--regenerate Delete and regenerate identity
--server HOST Signaling server hostname
--turn-url URL TURN server URL (e.g. turn:myserver.com:3478)
--turn-user USER TURN server username
--turn-credential PASS TURN server credential
--pin PIN PIN to protect access
--debug Enable verbose logging and browser debug UI
With --debug, the printed URL includes ?debug, which activates a browser-side debug UI showing connection steps. Without it, the browser shows a simple "Loading..." while connecting.
Identity and URLs
Each app gets its own persistent RSA keypair, stored at ~/.bitbang/<program_name>/identity.pem. The public key hash becomes the app's 128-bit ID, used in its URL -- so the URL stays the same across restarts. Use --regenerate for a new URL, or --ephemeral for a one-time session.
TURN
When a direct peer-to-peer connection isn't possible, bitba.ng provides a TURN relay, which carries only ciphertext. You can supply your own TURN server via the command-line options or the ice_servers constructor argument (browser-native WebRTC format). The defaults work fine for most setups.
How it works
Browsers normally connect to web servers over a TCP socket. BitBang replaces this with a WebRTC data channel:
The signaling server brokers the WebRTC handshake, then has no further involvement and never sees application data. The full story -- architecture, trust model, and origin -- is in the BitBang project README, the whitepaper, and Trustless Signaling document.
License
MIT
Contributing
Issues and pull requests are welcome.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file bitbang-0.1.56.tar.gz.
File metadata
- Download URL: bitbang-0.1.56.tar.gz
- Upload date:
- Size: 84.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
04583bfa435e93613c63789ce3deb2aacdd5f763a407cac2945332fe2ec98ae0
|
|
| MD5 |
f3e69d64ad455fb885ae59e09f2a9d1e
|
|
| BLAKE2b-256 |
0ff5a833c0a6ae5d2184a8d8de15352bf2e376a56aee6c3fd387a4acb6f3bb5b
|
File details
Details for the file bitbang-0.1.56-py3-none-any.whl.
File metadata
- Download URL: bitbang-0.1.56-py3-none-any.whl
- Upload date:
- Size: 71.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0a9627b678b4fe9688ea8132a014d64de832f4fb63f583955da8f346e2c0e005
|
|
| MD5 |
8b36545ca731cfe5505e91a113eda629
|
|
| BLAKE2b-256 |
c450de30fb1738c0cad58fbcc9bf240df9ab8b9347856dfd74a2f2bbbad9d645
|
