So you want to hack on Bitmask? Thanks, and welcome!

This document assumes a Linux environment.

There are also ongoing documents with notes for setting up an OSX and a Windows working environments too, contribution is very much welcome on those docs!

Running tests

Tox is all you need:


Test when changes are made to common/soledad

If you are developing against a non-published branch of leap.common or leap.soledad, run instead:

tox -e py27-dev

This expects leap_common and soledad repos to be checked out in the parent folder.


For debugging issues related to how tests are run by the gitlab CI, you need to install:

You probably want to add sleep 9000 to allow debuggin on the docker container. For convenience, you can execute the packaging step by doing:

make package_in_docker

Look at the Makefile to see the command that it’s actually used.

If you want to run an specific test, you can do it like this:

gitlab-runner exec docker --docker-privileged --env BITMASK_INVITE_CODE=xxx e2e_test_vpn

If you have a bad uplink, you might want to add --docker-pull-policy=if-not-present to that invocation.


There is a small explanation of the bitmask components that might be helpful to get you started with the different moving parts of the Bitmask codebase.

User Interface

The Javascript User Interface has its own guide for developers.


Read how to setup your python development environment to start coding in no time.


A must-read for debugging the Bitmask Core daemon is the manhole HowTo.


Bitmask VPN needs administrative privileges. For developing, you need to be sure that you have installed the privileged helpers and that you keep them udpated.


There are some guidelines for contributing code that you might want to check if you are insterested in developing with Bitmask.

Submitting a Bug

You can read more about how to submit a bug in the section on Testing and QA.


We keep a checklist for the release process.


Want to help, but you don’t know where to start? Come talk to us on irc or the mailing list!

Some areas in which we always need contribution are:

  • Localization of the client (talk to elijah).
  • Multiplatform gitlab runners
  • Windows and OSX packaging (talk to kali)
  • Windows Firewall integration for VPN
  • Migrating components to py3 (look for vshyba or kali).
  • Minimal C++ Qt client (see kali’s bitmaskqt5 repo)