Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
stem-client @ b48ce68

Lightnion is a JavaScript library that you can include on your webpage to let any modern browser make anonymous requests. Lightnion uses an untrusted proxy to interact with the Tor network. This proxy converts between protocols (Websockets to pure TCP). This repository also contains a Python Lightnion Tor client that we have been using for testing.

WARNING: At the moment Lightnion is alpha-level research software. Do not use it in production, or for anything that really requires anonymity. You are, however, more than welcome to experiment with Lightnion. Please provide feedback opening issues or writing to the authors.

Quick setup

Clone the repository and add it to your PYTHONPATH:

git clone --recurse-submodules lightnion
cd lightnion
virtualenv venv
source venv/bin/activate
pip install -r requirements.txt

You'll find some examples that showcase the Python Tor client under ./examples. For example, you could run (after setting up chutney, see below):

python3 examples/ 5000
python3 examples/ 5000
python3 examples/ 5000 7 0 8001

Interacting with the Tor network

Lightnion interacts with the Tor network. For testing and demo purposes we recommend to use a test network generated by chutney. To set one up you could do the following:

git clone
cp lightnion/tools/chutney/small-chut chutney # or read tools/chutney/
cd chutney
git apply ../lightnion/tools/chutney/sandbox_patch # disable sandbox if you need

This will setup and run a small Tor test network. See the notes for how to run Lightnion with the real Tor network.


To build the JavaScript lightnion.js library, run:

cd js-client
make # you'll need a java, tested with java-10-openjdk

You can then use lightnion.js in your website (make sure you are also running a proxy, see below). You can then use lightnion.js as follows:

// create a channel through the proxy

Params: (host, port, success, error, io, fast, auth, select_path, tcp_ports,info)
- Proxy host
- Proxy port
- success callback
- error callback
- socket io (default: websocket)
- fast connection (default: false)
- auth-enabled? (default: false)
- select path at client? (o/w: at proxy) (default: true)
- tcp ports to be used on streams. (default: [80,443])
- info: optional callback for step-by-step information
*/'', 4990, function(channel)

    // Callback interface (skip intermediate states)
    if (lln.state != lln.state.success)

    // Handle response of request
    var handler = function(response) {...};

    // Send HTTP GET request to

    tcp =, '', 80, handler)
    tcp.send('GET / HTTP/1.1\r\n' +

Starting the proxy

To start the proxy first install its dependencies

pip install -r requirements-proxy.txt

and then run it:

python -m lightnion.proxy

this will however only start the proxy and you will have to host lightnion.js and the demo files another way. Alternative, the proxy can host them for you by running:

python -m lightnion.proxy -vvv --purge-cache --static ./js-client/demo/: ./js-client/evaluation/:

You can now explore some of the demos:


We do recommend using chutney, you'll find some instructions within ./tools/chutney.

Tested with Python 3.7.0 against Tor version (git-45028085ea188baf).


This software is licensed under the BSD3 clause license. © 2018-2019 Spring Lab (EPFL) and contributors.


A light version of Tor portable to the browser







No releases published


No packages published