This is prototype-grade software!
Browsers Unbounded is a system for distributed peer-to-peer proxying. The Browsers Unbounded system includes a browser-based client which enables volunteers to instantly provide proxying services just by accessing a web page. However, Browsers Unbounded is not just a web application! The Browsers Unbounded system introduces software libraries and protocol concepts designed to enable role-agnostic multi-hop p2p proxying across the entire Lantern network or on behalf of any circumvention tool that chooses to integrate it.
Put another way, Browsers Unbounded is a common language which enables circumvention tool users to describe, exchange, and share the resource of internet access across network boundaries and runtime environments.
Module | Description |
---|---|
clientcore | library exposing Browsers Unbounded's high level client API |
cmd | driver code for operationalizing Browsers Unbounded outside of a controlling process |
common | data structures and functionality shared across Browsers Unbounded modules |
egress | egress server |
freddie | discovery, signaling, and matchmaking server |
netstate | network topology observability tool |
ui | embeddable web user interface |
Clone this repo.
Configure Mozilla Firefox to use a local HTTP proxy. In settings, search "proxy". Select
Manual proxy configuration. Enter address 127.0.0.1
, port 1080
, and check the box labeled
Also use this proxy for HTTPS.
Build the native binary desktop client: cd cmd && ./build.sh desktop
Build the native binary widget: cd cmd && ./build.sh widget
Build the browser widget: cd cmd && ./build_web.sh
Start Freddie: cd freddie/cmd && PORT=9000 go run main.go
Start the egress server: cd egress/cmd && PORT=8000 go run egress.go
Start a desktop client: cd cmd/dist/bin && FREDDIE=http://localhost:9000 EGRESS=http://localhost:8000 ./desktop
Decision point: do you want to run a native binary widget or a browser widget? To start
a native binary widget: cd cmd/dist/bin && FREDDIE=http://localhost:9000 EGRESS=http://localhost:8000 ./widget
. Alternatively, to start a browser widget, follow the
UI quickstart.
The widget and desktop client find each other via the discovery server, execute a signaling step, and establish several WebRTC connections.
The netstate module is a work-in-progress tool for observing Browsers Unbounded networks. netstate currently visualizes network topology, labeling each Browsers Unbounded node with an arbitrary, user-defined "tag" which may be injected at runtime.
netstated
is a distributed state machine which collects and processes state changes from Browsers Unbounded
clients. It serves a network visualization at GET /
. The gv
visualizer client looks for a
netstated
instance at localhost:8080
.
In the example below, we assume that Freddie is at http://localhost:9000
and the egress server
is at http://localhost:8000
:
Start netstated
: cd netstate/d && go run netstated.go
Start a widget as user Alice: cd cmd/dist/bin && NETSTATED=http://localhost:8080/exec TAG=Alice FREDDIE=http://localhost:9000 EGRESS=http://localhost:8000 ./widget
Start a desktop client as user Bob: cd cmd/dist/bin && NETSTATED=http://localhost:8080/exec TAG=Bob FREDDIE=http://localhost:9000 EGRESS=http://localhost:8000 ./desktop
Open a web browser and navigate to http://localhost:8080
. As Alice and Bob complete the
signaling process and establish connection(s) to one another, you should see the network you have
created. You must refresh the page to update the visualization.
The UI is bootstrapped with Create React App. Then "re-wired" to build one single js bundle entry using rewire.
The React app will bind to a custom <browsers-unbounded>
DOM el and render based on settings passed to the dataset.
In development, this html can be found in ui/public/index.html
. In production, the html is supplied by the "embedder" via https://unbounded.lantern.io/embed.
Example production embed:
<browsers-unbounded
data-layout="banner"
data-theme="dark"
data-globe="true"
data-exit="true"
style='width: 100%;'
></browsers-unbounded>
<script defer="defer" src="https://embed.lantern.io/static/js/main.js"></script>
This tables lists all the available settings that can be passed to the <browsers-unbounded>
DOM el via the data-*
attributes.
The "default" column shows the default value if the attribute is not set.
dataset | description | default |
---|---|---|
layout | string "banner" or "panel" layout | banner |
theme | string "dark", "light" or "auto" (browser settings) theme | light |
globe | boolean to include webgl globe | true |
exit | boolean to include toast on exit intent | true |
menu | boolean to include menu | true |
keep-text | boolean to include text to keep tab open | true |
mobile-bg | boolean to run on mobile background | false |
mobile-bg | boolean to run on desktop background | true |
editor | boolean to include debug dataset editor | false |
branding | boolean to include logos | true |
mock | boolean to use the mock wasm client data | false |
target | string "web", "extension-offscreen" or "extension-popup" | web |
In development, these settings can be customized using the REACT_APP_*
environment variables in the .env
or in your terminal.
For example, to run the widget in "panel" layout, you can run REACT_APP_LAYOUT=panel yarn start
. To run the widget with mock data,
you can run REACT_APP_MOCK=true yarn start
.
Settings can also be passed to the widget via the data-*
attributes in ui/public/index.html
. For example, to run the widget in "panel" layout,
you can set data-layout="panel"
in ui/public/index.html
.
If you enable the editor (by setting REACT_APP_EDITOR=true
or data-editor="true"
), you can also edit the settings dynamically in the browser using a UI editor the renders above the widget.
Note that the mock
and target
settings are not dynamic and therefore not editable in the browser. These two settings are static and must be set at the time the wasm interface is initialized.
Links:
cd ui
yarn
Development:
cp .env.development.example .env.development
yarn dev:web
and open http://localhost:3000 to view it in the browser.Production:
cp .env.production.example .env.production
yarn deploy
Work from the ui dir: cd ui
Configure your .env file: cp .env.development.example .env.development
REACT_APP_WIDGET_WASM_URL
to your intended hosted widget.wasm
file. If you are serving it from client
in step #8, use http://localhost:9000/widget.wasm. If you ran ./build_web.sh
(step #7) you can also use /widget.wasm
. To config for prod point to a publicly hosted widget.wasm
e.g. https://embed.lantern.io/widget.wasm
. If you know you know, if not, you likely want to use /widget.wasm
.REACT_APP_GEO_LOOKUP_URL
to your intended geo lookup service. Most likely https://geo.getiantem.org/lookup
or http://localhost:<PORT>/lookup
if testing geo lookups locallyREACT_APP_STORAGE_URL
to your intended iframe html for local storage of widget state and analytics. Most likely https://embed.lantern.io/storage.html
or /storage.html
if testing locallyREACT_APP_*
variables as needed for your development environment. See UI settings and configuration for more info.REACT_APP_DISCOVERY_SRV
, REACT_APP_DISCOVERY_ENDPOINT
, REACT_APP_EGRESS_ADDR
& REACT_APP_EGRESS_ENDPOINT
Install the dependencies: yarn
To start in developer mode with hot-refresh server (degraded performance): run yarn dev:web
and visit http://localhost:3000
To build optimized for best performance:
cp .env.production.example .env.production
(see Step 2)yarn build:web
To serve a build:
npm install -g serve
(or your lightweight http server of choice)cd build && serve -s -l 3000
and visit http://localhost:3000To deploy to Github pages: yarn deploy
Coming soon to a repo near you: yarn test
Work from the ui dir: cd ui
Install the dependencies: yarn
Configure your .env file: cd extension && cp .env.example .env
EXTENSION_POPUP_URL
to your intended hosted popup page. If you are serving it from ui
in step #6, use http://localhost:3000/popup. To use prod, set to https://embed.lantern.io/popup.EXTENSION_OFFSCREEN_URL
to your intended hosted offscreen page. If you are serving it from ui
in step #6, use http://localhost:3000/offscreen. To use prod, set to https://embed.lantern.io/offscreen.To start in developer mode with hot-refresh server:
yarn dev:ext chrome
yarn dev:ext firefox
This will compile the extension and output to the ui/extension/dist
dir. You can then load the unpacked extension in your browser of choice.
ui/extension/dist/chrome
dir. ui/extension/dist/firefox/manifest.json
file. ui/extension/dist/edge
dir.yarn build:ext chrome
yarn build:ext firefox
This will compile the extension and output a compressed build to the ui/extension/packages
dir.