Skip to content

Get Started

Implementation - Step 1: Assets/Binaries

  • GeoIP files:
    • Your application will need geoip and geoip6 files. Due to this issue they currently cannot be provided via a dependency that can be easily updated. Until then, you’ll have to provide them.
    • Steps:
  • torrc file:
    • Not needed
    • Your application’s torrc file gets created for you based on what you have stored in TorServicePrefs. If nothing is in TorServicePrefs for that particular setting, then it will fall back on your static/default ApplicationDefaultTorSettings that you supply upon initialization of TorServiceController.Builder.
  • Tor Binaries:
    • I use The GuardianProject’s tor-android project to re-package and provide only the binaries, as that’s all which is needed by TOPL-Android. As of version, the binaries are simply copied instead of being re-built (prior versions I was building, but build reproducability is problematic…) which can be verified by checking the sha256sums (see the repo’s README for instructions on how to do that).
      • They can be found here.
      • The only difference is the contents of what you are importing as a dependency. I package them in the jniLibs directory so that the Android OS will automatically extract them to your application’s /data/app/... directory, and include no unnecessary classes or resources; just the binaries.
      • Android API 29+ no longer supports execution of executable files from your application’s /data/data/ directory, and must now be installed in the context.applicationInfo.nativeLibraryDir directory (aka, /data/app/...) to execute.
      • Nothing more is needed in terms of configuring initialization via the TorServiceController.Builder.useCustomTorConfigFiles, as files will be installed in the correct directory, and named to match what topl-service looks for.
    • If you wish to use GuardianProject’s dependency, see tor-android.
      • You’ll need to use their NativeResourceInstaller to install the binaries.
      • You’ll need to also implement TorServiceController.Builder.useCustomTorConfigFiles method when initializing topl-service and provide it with your own TorConfigFiles.
  • Transport Plugin Binaries:
    • Currently unsupported. Working on it!!!


Tor Binaries are ~8MB for each ABI, so it’s advised that builds are split to keep apk sizes down. See the sampleapp‘s build.gradle file for more details. here

Implementation - Step 2: topl-service

Multi-Module projects

  • If you have a tor module in your project that extends the api’s in TorServiceController to centralize control of topl-service, other modules depending on it need only import the topl-service-base module which provides all of the necessary public classes/abstractions.

  • In your tor module’s build.gradle file, add the following to the dependencies block:

    api "io.matthewnelson.topl-android:topl-service-base:2.1.1"

Using the SNAPSHOT version of topl-service

  • In your Application module’s build.gradle file, add the following (outside the android block):

    repositories {
        maven {
            url ''

  • In your Application module’s build.gradle file, add (or modify) the following in the dependencies block:

    implementation 'io.matthewnelson.topl-android:topl-service:2.2.0-SNAPSHOT'


    SNAPSHOT versions are ever changing and may contain not yet fully fleshed out features. Do not ship a release.