Bitmask Android Client

This repository contains the source code for the Bitmask Android client. Bitmask Android offers one-click free VPN service from trusted providers of the LEAP stack.

To learn about the stack, visit

Please see the issues section to report any bugs or feature requests, and to see the list of known issues.

Table Of Contents



We will assume for convenience that you are installing on a Debian- or Ubuntu-based GNU/Linux machine. (Patches welcome with instructions for Mac, Windows, or other GNU/Linux distributions!)

The Bitmask Android Client has the following system-level dependencies:

You can install them as follows:


Install with:

sudo apt install default-jdk

C Libraries

These are necessary to make sure the program cross-compiles to 32-bit architectures successfully from 64-bit GNU/Linux machines:

sudo apt install make gcc file install lib32stdc++ lib32z1

Android SDK

With Android Studio

All of the Android SDK and NDK packages are downloadable through Android Studio, which (sadly) is probably the most hassle-free way to go about things.

You can download Android studio here:

Once you've got it installed, use the SDK Manager tool (Android figure Icon with blue arrow second from the right in the tool pane) to download all the Android SDK and NDK depencencies listed above.

With Bash

Alternatively (eg: for build machines), you may download and unzip the android-sdk bundle from Google as follows (assuming an install location of /opt/android-sdk-linux:

curl -L -o  \
    && unzip -q -d /opt/android-sdk-linux \
    && rm -f

To download the NDK (for cross-compiling and running the C code used in ics-openvpn), use:

curl -L -o  \
    && unzip -d /opt/android-sdk-linux/android-ndk-r16b \
    && rm -rf

After updating your PATH (see next step), you may now use the sdkmanager tool bundled with android-sdk to browse and install new sdk packages from Google.

To browse all available packages, run:

sdkmanager --list

To search for available packages of a certain type (eg: tools), run:

sdkmanager --list | grep tools

To install all of the dependencies listed above (targetting SDK versions 23 - 26), run:

sdkmanager tools
sdkmanager platform-tools
sdkmanager extras;android;m2repository
sdkmanager extras;google;m2repository
sdkmanager build-tools;27.0.3
sdkmanager build-tools;25.0.2
sdkmanager build-tools;23.0.3
sdkmanager platforms;android-27
sdkmanager platforms;android-25
sdkmanager platforms;android-23

Updating Your Path

Once you've installed Android SDK & NDK packages, you need to modify your PATH so you can invoke all the programs you just installed. You can do that with something like the following in your ~/.shellrc or ~/.bash_profile:

export ANDROID_HOME=<path/where/you/installed/android/sdk>
export PATH=$ANDROID_HOME/platform-tools:$PATH
export PATH=$ANDROID_HOME/tools/bin:$PATH

NOTE: On GNU/Linux machines, Android Studio installs the Android SDK in ~/Android/Sdk/. Our dockerfile installs it in /opt/android-sdk-linux. You can install it wherever you want! Just be sure to remember where so you can add it to your PATH! :)

With Docker

Geesh! If all that above seems like a lot, it is!

To keep ourselves from messing it up all the time everyone someone new joins the project, we made a Dockerfile that creates the above environment with one line. You can pull the image and run builds from inside it, or consult the Dockerfile itself for requirements that your system might need but be missing.

Assuming you've already installed docker, you can pull the image with:

docker pull

Run the image with:

docker run --rm -it

More likely than not, you'll want to run the image with the source code mounted. You can do that with:

cd <path/to/bitmask_android>
docker run --rm -it -v`pwd`:/bitmask_android -t


We depend on ics-openvpn as an interface to Android's OpenVPN implementation. We include it as a git submodule in our project, which requires that we initialize and update it (and its respective upstream submodule dependencies) in order to compile and run Bitmask Android.

We do so with:

cd <path/to/bitmask_android>
git submodule init
git submodule update --init --recursive


You have lots of options for compiling, all of which will output Android-executable apk packages to /bitmask_android/app/build/outputs/apk/.

Just Build It!

If you compile the project for the first time you'll have to compile the dependencies. This can be done with:


This command will create all libs we need for Bitmask.

If you want to to have a clean build of all submodules run


before you call ./ That script removes all build files and does the git submodule init and update job for you.

You are then welcome to run:

./gradlew build

This will compile the code and run the tests, but not output any apk packages. As such, it's not all that useful. :)

Debug APKs

To assemble debug packages for running locally or testing in CI, run:

./gradlew assembleDebug

This will output app-insecure-debug.apk and app-production-debug.apk to /bitmask_android/app/build/outputs/apk/.

Release APKs

To assemble release packages, run:

./gradlew assembleRelease

This will output app-insecure-release.apk and app-production-release.apk to /bitmask_android/app/build/outputs/apk/.

Signed Release APKs

If you want to release a signed APK (which you must do to publish the app to the Google Play store), you'll have to create a file in the project root with the following structure:

storePasswordProperty=<store password without quotation marks>
keyAliasProperty=<key alias without quotation marks>
keyPasswordProperty=<key password without quotation marks>

Building In Docker

If you want to make sure the environment you use to build APKs matches exactly the environment that Gitlab will use to build and publish artifacts, you can run any of the above build commands from inside Docker. To assemble a release build this way, run the following commands:

$ cd <path/to/bitmask_android>
$ sudo docker run --rm -it -v `pwd`:/bitmask_android
# cd /bitmask_android
# ./
# ./
# ./gradlew assembleRelease

Running Tests

To run the automated tests:

  1. Run an emulator
  2. Unlock Android
  3. Issue the command ./gradlew connectedCheck
  4. Pay attention and check the "Trust this app" checkbox, if you don't do so tests won't run.

Debugging in an Emulator

You can run the app in an emulator running any version of Android and simulating (almost) any device. To run it you'll have to create an emulator, run the emulator, and then load an assembled APK of the app onto the emulator. (You can then use all sort of nifty tools in Anroid Debug Bridge to tail the logs and debug the app.)

Assuming you've already tackled (or don't need to tackle) the Debian Gotchas listed below, you can do that using either Android Studio or a bash shell as follows:

From Android Studio

To create an emulator:

To run a pre-existing emulator:

To run the app:

From the Shell

To list the available avd images for creating an emulator:

avdmanager list

To create an emulator:

avdmanager create avd

To list the emulators you have already created:

avdmanager list avd

To run a pre-existing emulator called Nexus_5_API_25:

emulator @Nexus_5_API_15

Verify the device is running with:

adb devices

You should see something like:

List of devices attached
emulator-5554 device

Install APK with:

abd install <path/to/your>.apk

Uninstall with:

abd uninstall se.leap.bitmaskclient

Install with option to reinstall:

abd install -r <path/to/your/apk>

Debian Gotchas

If you are running Debian on a 64-bit machine, your emulator will likely not work out of the gate. Test to see if this is the case by:

1. Virtualization Not Enabled

Boo! Try turning it on. The second half of this article is a decent enough guide.

2. Unpatched Filepaths Bug

Symptoms: If you have this bug, you will see something like the following when you try to spin up an emulator:

[140500439390016]:ERROR:./android/qt/qt_setup.cpp:28:Qt library not found at ../emulator/lib64/qt/lib
Could not launch '../emulator/qemu/linux-x86_64/qemu-system-i386': No such file or directory

As documented here, there is a standing bug in the version of emulator packaged for emulator that assumes it always runs from within the $ANDROID_HOME/emulator directory, and can thus safely use relative filepaths, when in fact this is almost never the case. (Cool bug!)


You have a couple options. The second is more robust:

  1. Always run emulator from within its own directory (clunky!):
 cd "$(dirname "$(which emulator)")"
 emulator <name_of_your_emulator>
  1. Insert a line in your ~/.bashrc to automatically navigate to the correct directory (and back) whenever you invoke emulator:

    function emulator { pushd `pwd`; cd "$(dirname "$(which emulator)")" && ./emulator "[email protected]"; popd;}

3. Outdated GL Libraries

Symptoms: If you have this bug, you will see something like the following:

libGL error: failed to load driver: swrast
X Error of failed request:  BadValue (integer parameter out of range for  operation)
# redacted incredibly long stack trace

As documented here, the current emulator package ships without outdated versions of LibGL libraries. To work around this:

  1. Install modern GL libriaries with:
sudo apt-get install mesa-utils
  1. Ensure that emulator always uses the correct libraries by either:

    a. always calling emulator with the -use-system-libs flag, like so:

    emulator -use-system-libs -avd Nexus_5_API_25

    b. adding the following line to your ~/.bashrc or ~/.bash_profile:


Special Android Studio Debian Bonus Gotcha:

Assuming you have made all the above fixes (great job!), to be able to launch emulators from Android Studio, you must either:

  1. Use the environment variable solution above (option a), then always launch Android Studio from a bash shell with:

This means never using the desktop launcher. :(

  1. If you want to use the desktop launcher:

    • You must always launch emulators from the terminal. :(
    • But: you can quickly access a terminal inside of Android Studio with OPTION-F12

Updating Submodules

If you need to refresh of our upstream dependency on ics-openvpn, you may do so with:

cd <path/to/bitmask_android>
./gradlew updateIcsOpenVpn


cd <path/to/bitmask_android>
cd ics-openvpn
git remote add upstream
git pull --rebase upstream master

A bunch of conflicts may arise. The guidelines are:

1. Methods in HEAD (upstream) completely removed from Bitmask should be removed again (e.g. askPW)
2. Sometimes, Dashboard.class is in Bitmask while in ics-openvpn it is replaced by MainActivity.class and other classes. Keep removing them to keep Dashboard.class in there.
3. Some resources files are stripped from several entries. Remove them if possible (check the code we compile is not using anything else new).


This project bases its work in ics-openvpn project.

Reporting Bugs

Please file bug tickets on our main development platform. You can either create an account on or simply login with your or account to create new tickets.


Please fork this repository and contribute back using pull requests.

Our preferred method for receiving translations is our Transifex project.

Any contributions, large or small, major features, bug fixes, additional language translations, unit/integration tests are welcomed and appreciated but will be thoroughly reviewed and discussed.