OnionCat on Android

Screenshot_2015-09-05-12-17-01This article is about how to compile and run OnionCat on Android. Unfortunately, there is no Android app which simply enables it, due to the lack of programming power.1 But if you are familiar with compiling projects and using ADB and the command line, this should be no big deal for you. Here’s how it works!

Root Your Phone

A requirement is that you Android smartphone is rooted since OnionCat accesses the tunnel device and configures an IPv6 address. Please do not ask how to root your phone! Please have a look at xdadevelopers instead.

Install Android NDK

You have to install the Android NDK. Go to developer.android.com/ndk and download and install it according to the instructions found on this page. Please do not forget to set the environment variable ANDROID_NDK properly. The best place to do this is .bashrc or .zshrc (or whatever shell you use). In my case this is


Download OnionCat

Download the latest OnionCat package from www.cypherpunk.at/ocat/download/Source/current, extract the package and cd into it.

$ tar xfz onioncat-0.2.2.r569.tar.gz
$ cd onioncat-0.2.2.r569

Download the android_configure shell script into the previously extracted build directory of OC. This is a simple script which sets up the environment for cross-compilation and finally runs OnionCat’s native configure script. Run the script with

$ sh android_configure

Now simply run make.

$ make

This will compile OnionCat and finally produce an ARM 32 bit binary. You’ll find the executable file in src/ocat. ARM may not be the right platform for your smartphone. You’ll find the type of CPU in Settings->About Phone->CPU. If it is different you have to adjust the android_configure script accordingly (enivronment variables ANDROID_PREFIX and SYSROOT).

Copy OnionCat to Your Phone

Copy the executable to your Android phone. A good place for it is e.g. /system/bin. Make sure that it is executable. The best way to do the following tasks is either on the adb shell or directly within a terminal on your smartphone (or tablet). ADB (the Android Debug Bridge) is part of the Android SDK. Most Linux distros also have a package for it. I assume that you copied the ocat executable to your sdcard. Now run the adb shell, copy the file, and make it executable.

$ adb shell
shell@kumquat:/ $ su
root@kumquat:/ # cp /sdcard/ocat /system/bin
root@kumquat:/ # cd /system/bin
root@kumquat:/system/bin # chmod 755 ocat
root@kumquat:/system/bin #

 Finally test if the OnionCat executable is fine by simply starting it without any options. It should output a short help message.

root@kumquat:/system/bin # ocat
onioncat 0.2.2.r571 (c) Bernhard R. Fischer (OnionCat mode)
usage: ocat [OPTIONS]
-a create connect log at "$HOME/.ocat/ocat_connect_log" (default = 0)
-b daemonize (default = 1)
-B do not daemonize (default = 0)
-h display usage message

Install Orbot

Screenshot_2015-09-05-12-01-56Now install Orbot from F-Droid or GooglePlay and start the app. Go into the Settings and enable Hidden Service Hosting and choose 8060 to be the Hidden Service Port. Finally close the app and restart it. Connect Orbot to the Tor network by long-pressing the push button in the middle of the app. It will first turn yellow and then green if it’s ready.

Orbot will create the hidden service which is necessary for OnionCat. You can find the Onion Hostname (Onion ID) either in the Orbot Settings under Onion Hostname or on the command line in the appropriate data directory:

root@kumquat:/ # cd /data/data/org.torproject.android/app_data/hs8060
root@kumquat:/data/data/org.torproject.android/app_data/hs8060 # cat hostname
root@kumquat:/data/data/org.torproject.android/app_data/hs8060 #

This is your unique Onion Hostname of your Android phone. You are now ready to start OnionCat.

Run OnionCat

Make sure that there is a device node for the tunnel interfaces under /dev/tun.

root@kumquat:/ # ls -l /dev/tun
ls: /dev/tun: No such file or directory
1|root@kumquat:/ #

If this fails as show above you have to insert tun kernel module.

root@kumquat:/ # modprobe tun
root@kumquat:/ # ls -l /dev/tun
crw-rw—-    1 system       vpn            10, 200 Sep  5 21:16 /dev/tun
root@kumquat:/ #

Now you are ready to run OnionCat with the following command. Of course, you have to insert your correct Onion Hostname.

root@kumquat:/ # ocat -T /dev/tun -r -B xxxxxxxxxxxxxxxx.onion
Sat, 05 Sep 2015 21:17:26.358 +0200 [0:main      :  info] onioncat 0.2.2.r571 (c) Bernhard R. Fischer (OnionCat mode)
Sat, 05 Sep 2015 21:17:26.380 +0200 [0:main      :  info] IPv6 address fd87:d87e:eb43:xxxx:xxxx:xxxx:xxxx:xxxx
Sat, 05 Sep 2015 21:17:26.380 +0200 [0:main      :  info] TUN/TAP device tun0
Sat, 05 Sep 2015 21:17:26.381 +0200 [0:main      :  info] starting packet forwarder

Now test it. The best way is to ping6 some other OnionCat host of which you know that it is up.

root@kumquat:/ # ping6 fd87:d87e:eb43:744:208d:5408:63a4:ac4f
PING fd87:d87e:eb43:744:208d:5408:63a4:ac4f(fd87:d87e:eb43:744:208d:5408:63a4:ac4f) 56 data bytes
64 bytes from fd87:d87e:eb43:744:208d:5408:63a4:ac4f: icmp_seq=5 ttl=64 time=387 ms
64 bytes from fd87:d87e:eb43:744:208d:5408:63a4:ac4f: icmp_seq=6 ttl=64 time=275 ms
64 bytes from fd87:d87e:eb43:744:208d:5408:63a4:ac4f: icmp_seq=7 ttl=64 time=253 ms
64 bytes from fd87:d87e:eb43:744:208d:5408:63a4:ac4f: icmp_seq=8 ttl=64 time=250 ms
64 bytes from fd87:d87e:eb43:744:208d:5408:63a4:ac4f: icmp_seq=9 ttl=64 time=269 ms

Screenshot_2015-09-05-12-28-12If this works you are ready to use the OnionCat VPN. All OnionCat destination addresses will automatically be routed through your OnionCat and OrBot respectively.

Have phun and don’t hesitate to contact me!


  1. But OnionCat is a free project, thus you are invited to write a simple Android app for it 😉


1 ping

Skip to comment form

  1. Would be great to make a real GUI android app out of this.

    1. Yes, definitely. But GUI programming is not my cup of tea. And unfortunately during all these years of OC development, nobody volunteered to write a GUI :/

    • Dalton on December 5, 2016 at 11:10 pm
    • Reply

    Instead of writing the GUI, why not convince the Guardian Project to add an OnionCat option on Orbot?

    1. Of course, that’s a good idea 🙂
      So OnionCat is an open project, feel free to implement it 😉

  2. I like the idea, maybe i should add this to orbot….i’m thinking about it, i will ask about it to dev-list to know the opinion of the others

  3. Ok , here we go:


    keep in touch

  4. Renamed to https://github.com/arrase/Onioncat-Android

  5. First alpha release available:


  6. First beta release available, all is running and the UI is ….. less ugly


    • Vadym on December 6, 2017 at 6:59 am
    • Reply

    Why not to use https://developer.android.com/reference/android/net/VpnService.html instead of native implementation requiring a root.

    1. Well, this is a free and open source project. Thus, feel free to implement it 😉

    • ru-chan on August 13, 2019 at 8:13 pm
    • Reply


    • 桑田成海 on September 11, 2019 at 7:10 am
    • Reply


  1. […] just wrote an article about OnionCat on Android. There is a readily compiled ARM binary found at […]

Leave a Reply

Your email address will not be published.