Whonix Wiki Download Docs News Support Tips Issues Contribute DONATE

Tor Browser Sandbox (Linux Alpha) - Coming Soon

Sandboxing Tor Browser in Non-Qubes-Whonix

Warning: These instructions are extremely alpha. They currently only work reliably with the 32-bit version of Whonix. Testers or advanced users only![1]


A sandbox is a secure environment in which you can run the Tor Browser and mitigate exploit vectors which would otherwise deanonymize you or infect your computer. In essence, the Tor Browser is run in a limited awareness container that is prevented from interacting with the rest of your computer.

Sandboxing reduces the opportunities for an attacker to easily identify real IP and MAC addresses, install malware, browse your files or otherwise deanonymize you.[2] A spate of recent attacks on the Tor Browser in the wild suggest this is a prudent approach for cautious users, or those facing significant risks.

The Tor Browser sandbox is compatible with either the “release”, “alpha” or “hardened” Tor Browser series. However, the sandboxed “hardened” Tor Browser is the least-tested combination by Tor developers.[3]

Sandboxing Effects on Tor Browser Functionality

While sandboxing improves security, some functionality is lost either by design or inadvertently. In addition, some functions like sound must be optionally configured. As of December 2016, broken items include:[4]

  • Foreign language support;
  • The meek pluggable transport; and
  • Manual checks for Tor Browser updates.

The Tor Browser sandbox is unlikely to ever support:

  • The FTE pluggable transport;
  • Hardware-accelerated 3d rendering;
  • Printing, except to a file;
  • Connections outside of the Tor network; and
  • Compatibility of the “hardened” Tor Browser with a grsec kernel (due to ASAN/Pax conflicts).

Audio support, the Tor ciruit display and installing or updating Tor Browser addons also require manual configuration changes.[5]

Tor Browser Sandbox Dependencies

In order to install and run the sandbox, two things are required:

  • Several dependencies available in Debian Jessie backports; and
  • A newer (Whonix-14-developers-only) version of the control-port-filter-python for Tor cookie control protocol authentification.[6]

Installing sandboxed-tor-browser Dependencies

(1) Boot your Whonix-Workstation TemplateVM

(2) Enable jessie-backports

sudo su -c “echo -e ‘deb http://http.debian.net/debian jessie-backports main’ > /etc/apt/sources.list.d/jessie-backports.list”

OR to use the .onion mirror

sudo su -c “echo -e ‘deb http://vwakviie2ienjx6t.onion/debian jessie-backports main’ > /etc/apt/sources.list.d/jessie-backports.list”

(3) Use apt-pinning before installing dependencies[7]

Open /etc/apt/preferences.d/debian-pinning.pref in an editor with root rights.

If you are using a graphical Whonix, run:

kdesudo kwrite /etc/apt/preferences.d/debian-pinning.pref

If you are using a terminal-only Whonix, run:

sudo nano /etc/apt/preferences.d/debian-pinning.pref


Package: *
Pin: release a=stable
Pin-Priority: 700

Package: *
Pin: release a=jessie-backports
Pin-Priority: 650

Package: *
Pin: release a=testing
Pin-Priority: 600

Package: *
Pin: release a=unstable
Pin-Priority: 550

Package: *
Pin: release a=experimental
Pin-Priority: 500


(4) Update your package lists and install sandboxed-tor-browser dependencies

sudo apt-get update

sudo apt-get -t jessie-backports install golang bubblewrap libseccomp2 libseccomp-dev

(5) Install additional dependencies[8]

sudo apt-get install gnome-themes-standard gnome-themes-standard-data

Installing the Whonix-14 tor-controlport-filter[9]

Note: This process must be repeated on both the Whonix-Gateway and Whonix-Workstation.

(1) Upgrade to the Whonix-14 work in progress

sudo whonix_repository --baseuri https://deb.whonix.org --enable --repository developers

sudo su
export DEBDEBUG=1
export tpo_downloader_debug=1

apt-get update

find . /var/lib/apt | grep -i inrelease | xargs cat

apt-get --yes dist-upgrade

apt-get --yes autoremove

(2) Test the tor-controlport-filter is working

In the Whonix-Gateway run:

nc 9051

Type “something”. You should see the reply:

510 Command filtered

In the Whonix-Workstation run:

nc 9151

Type “something”. On the gateway you should see some tor-controlport-filter by Tails debug output.

Downloading the Tor Browser Sandbox

(1) Download the sandboxed-tor-browser binaries and signing key from the Tor Project[10]

In the Whonix-Workstation VM run:

wget https://www.torproject.org/dist/torbrowser/6.5a6/sandbox-0.0.2-linux64.zip

wget https://www.torproject.org/dist/torbrowser/6.5a6/sandbox-0.0.2-linux64.zip.asc

(2) Download the Tor Project signing key and verify the zip file


gpg --recv-keys “EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290”

gpg --verify sandbox-0.0.2-linux64.zip.asc

(3) Unzip the sandbox


unzip sandbox-0.0.2-linux64.zip

Using the sandboxed-tor-browser

To start the sandbox, simply run:


And select the Tor Browser version you are currently using in your Whonix-Workstation configuration.


  • sandboxed-tor-browser is also a Tor Browser downloader similar to tb-updated / torbrowser-launcher;
  • Whonix network settings are auto-detected as system Tor and there is no need to configure settings manually; and
  • If you wish to check the sandboxed-tor-browser is correctly using the system Tor process anyhow, in a terminal run:

env | grep TOR

The output should show:


is set as an environment variable.

Sandboxing Tor Browser in Qubes-Whonix

To Do.

The Tor Browser alpha sandbox is currently blocked in both the Qubes Debian and Qubes-Whonix Templates due to problems with bubblewrap.[6][11][12][13][14]

A recommended interim solution is to use Firejail in Qubes-Whonix to better contain the Tor Browser application.[15]


[1] These steps can be modified slightly to work in a (non-Qubes) Debian Jessie VirtualBox VM
[2] https://blog.torproject.org/blog/q-and-yawning-angel
[3] https://blog.torproject.org/blog/tor-browser-65a6-hardened-released
[4] https://trac.torproject.org/projects/tor/wiki/doc/TorBrowser/Sandbox/Linux Some of these bugs will be fixed at a later date.
[5] The Tor circuit in Tor Browser is disabled by default in Whonix anyhow
[6] Tor Browser Sandbox (Linux Alpha) - Coming Soon
[7] For safe mixing and matching of packages from different Debian repository branches without breaking your base distribution
[8] https://trac.torproject.org/projects/tor/ticket/21048
[9] https://www.whonix.org/wiki/Dev/Control_Port_Filter_Proxy#tor-controlport-filter_by_Tails
[10] https://www.torproject.org/projects/torbrowser.html.en#downloads-alpha
[11] https://trac.torproject.org/projects/tor/ticket/21077
[12] https://github.com/QubesOS/qubes-issues/issues/2540
[13] https://github.com/projectatomic/bubblewrap/issues/134
[14] Apparmor and grsec have been ruled out as blockers. Upgrading to Debian Stretch in the TemplateVM in Qubes does not work, nor does changing the Debian VM dom0 kernel via pvgrub
[15] To do: insert wiki reference to Firejail entry when complete

1 Like



Stop building 32 bit sandboxed-tor-browser binaries.

Since I merged #20940, x86 support has been deprecated, and binaries for that platform should no longer be built.

The wiki entry is done and is awaiting a reviewer to approve it.

1 Like


Doing some nitpicking on top.

Please don’t copy and paste from wiki templates. The goal is to avoid text duplication. The beauty of wiki templates is, that only the text in the wiki template needs to be changed.

Done here:

Duplication / manual copy and paste generally should be avoided. Otherwise when instructions change, we have to change them in X locations. And if these instructions derivate in two places, we end up with two users claiming to have done the same thing, but actually another thing. So replaced the upgrading to Whonix 14 developers-only instructions with a link to these. (We could make that a template, but well.)

Done here:

Lastly, please don’t use footnotes inside = titles =, since then the anchored links look bad.

These are just minor things. None of this speaks against directly editing the wiki, since these are easily sorted out on top.


We need to revisit the dependencies in the wiki.

Ever-helpful advice below :wink:


On January 3rd, 2017 Anonymous said:

Working instructions for non-Qubes-Whonix using the available binaries is below. This should also work with other platforms with minor changes:


Sandbox is not working in Qubes-Whonix due to problems (unresolved) with bubblewrap, see here:


Even the bubblewrap and Qubes developers are mystified, since the Qubes kernel is very similar to upstream kernel.

Yawning, does this info help to further investigate that Tor Ticket re: “Can’t mount proc on /newroot/proc: Operation not permitted”?


On January 3rd, 2017 yawning said:

At a glance, those instructions are pulling in unneeded dependencies (there is a difference between build and run-time dependencies for the project). But I don’t use Qubes-Whonix at all, or Debian for that matter so I can’t really comment on the rest of it.

Hmm. Revisiting:


Now shows:


Building sandboxed-tor-browser requires:

A C compiler with development libraries for Gtk+3, libnotify, and X11.
gb (​https://getgb.io/)
Go (Tested with 1.7.x) 


Running sandboxed-tor-browser requires:

A modern Linux system on the x86_64 architecture.
bubblewrap >= 0.1.3 (​https://github.com/projectatomic/bubblewrap).
Gtk+ >= 3.14.0
(Optional) PulseAudio
(Optional) The Adwaita Gtk+-2.0 theme (Install gnome-themes-standard on Ubuntu).
(Optional) libnotify 

Since we are grabbing the binaries, don’t we only need to pull in bubblewerap from Jessie backports for our instructions and maybe the Adwaita theme? That is, golang is only needed for manual builds (scrap it)?

What about the libseccomp2 and libseccomp-dev dependencies - why did we require that? Whonix-14 requirement?

It’s notable that Yawning doesn’t use Qubes or even Debian. You’d think someone paranoid about computing wouldn’t default to other Linux VM solutions.

Heaven forbid he/she assumes the monolithic (huge) Linux kernel is trustworthy or secure in any other general purpose distro, since we are looking at 10s of millions of lines of code in the kernel these days.

Joanna notes that it is impossible to ever secure the computing base of something so large and full of 1000s of undiscovered coding errors. Thus, it is only safe to assume future compromise and run compartmentalized solutions and isolation of dangerous elements e.g. USB, GUI, networking -> hence Qubes’ evolution.

1 Like

Can you try please which dependencies are unnecessary? The thing is - with the dependency it starts - without - it does not start.

I don’t think there is a middle ground aka “missing dependency - starts - think you are using bubblewrap - but surprise, it is ineffective”.


I don’t have extra hardware to be able to test this unfortunately, nor do I run dual-boot systems due to their inherent insecurity. I think @HulaHoop is running plain non-Qubes-Whonix, perhaps he could help check the dependencies on a cloned template?

If not, I suppose it doesn’t really matter, since all it means is some extra software is being pulled in that is not being used, and you have already successfully tested this…

1 Like

Some really great progress wrt bubblewrap in Qubes in the ticket.


1 Like

To translate it, I think the following is the only additional command one has to run before being able to run bubblewraped Tor Browser in Qubes.

sudo umount /proc/xen
1 Like

That’s great!

So, can Qubes-Whonix users just follow the instructions here:

with an additional step of:

sudo umount /proc/xen

before launching with:



Let me know, and I can trial this for you ASAP, as I’m dying to run this sandbox in Qubes. I’d love to also run it in a Whonix-WS dispVM successfully. I can also check the dependencies stuff at the same time.

PS I’m holding off on grsec testing on Whonix templates, as Coldhak is definitely working on it currently. So there is some reason why it is separate work, otherwise they would have recommended the same steps as per the Debian-8 Template. Unless you have it working already in your set-up?

Debian-8 coldkernel is running like a dream though. Very stable.

Yes, please try.

If it works great in Qubes Debian 8 template, it very much should so so in Qubes-Whonix due to no differences in kernel. At most apparmor might no longer load. Dunno. Haven’t gotten around to testing it yet.

I wonder if bubblewrap will work in combination with grsecurity. Please try.

(Answered in chronological order.)

In the non-Qubes-Whonix guide for sandboxing, we have instructed to download the 64-bit version of the alpha sandbox by mistake?


Or is this okay, because the templates are updated to the ‘Whonix-14’ in progress? If it does need to change, then I’ll edit as follows.

Step 1 of the Download would need to point to instead:

wget https://www.torproject.org/dist/torbrowser/6.5a6/sandbox-0.0.2-linux32.zip

wget https://www.torproject.org/dist/torbrowser/6.5a6/sandbox-0.0.2-linux32.zip.asc

And this part of step 2 changed to:

gpg --verify sandbox-0.0.2-linux32.zip

Let me know.

Once Whonix 14 is released, these instructions for non-Qubes-Whonix need to be edited to remove reference to ‘updating to Whonix work in progress’. Might be worth noting on phabricator somewhere, as I know you have a high priority item for this.

1 Like

Just checking in here:

  1. Can we expect that updating to Whonix-14 in progress also sets everything to Debian Stretch in the templates?
  2. We should accept any updated installer scripts for swdate and pulse (maybe not the latter) when doing the full upgrade then to Stretch?
  3. Checks for the updated control-port-filter in the wiki e.g. nc commands, are only for non-Qubes-Whonix and not Qubes-Whonix I believe?
  4. Proper sys-whonix technique in Qubes for testing updated (Whonix-14 GW) is to simply change the template over in Qubes settings OR create an alternative sys-whonix so networking isn’t completely (potentially) borked?

Anyhow, to date my updated ‘sandboxed’ WS and GW templates segfault when I try to open Konsole with some vague library libkdeul.so, after full Whonix-14 developers and Debian Stretch updates, so they seem to be broken.

I don’t have any issues with a Debian-9 template updated using Qubes recommended method, so I’ll just test first if sandboxed Tor Browser running off that will work i.e. starting with a simple platform first.

This should at least answer the issue around current compatibility of Qubes kernels and whether bubblewrap issues are sorted, plus required dependencies i.e. only starting with bubblewrap and moving up from there until the thing actually starts.

PS Those ‘additional dependencies’ gnome-themes-standard gnome-themes-standard-data are already installed in the upgraded templates, so that step is apparently not needed for Qubes-Whonix.

I also fixed the wiki entry which was referring to unzipping an .asc file, instead of the .zip file.

One step forward, three steps back :wink:

1 Like

I guess so.

It didn’t when we discussed this last time. But at the current state of the developers repository it is required to upgrade to stretch as per these instructions:


( updating Whonix from jessie to stretch / Migration to Gnome-Shell / port to GNOME-ish applications )

The developers repository currently is in a broken state. Getting the upgrade through requires some apt-get / dpkg gymnastics, control-port-filter-python does not work for some reason and networking is broken in the workstation (we might have to port form ifupdown to systemd-networkd). I can notify you once the developers repository is back to a working state and/or when there will be Whonix 14 developers-only downloadabe images.

I don’t know what you mean by that.

For Qubes-Whonix only the IP would be different. The IP of eth1. The checks won’t be required for anything near release.

In fact I have whonix-gw / whonix-ws templates based on Whonix stable-proposed-updates. Then cloned these templates. Made them whonix-gw-dev / whonix-ws-dev. And the derivative template based VMs sys-whonix-dev / anon-whonix-dev. If something goes wrong, I can still use the stable ones.

Fixed in wiki to 32bit.

Ah - that makes sense now why it broke. Please do notify on this thread when the depository is working and/or Whonix 14 images are available for download.

I mean during a full update of a template, we accept any changes when the a message pops up like e.g:

“Setting up ifupdown …
Configuration file `/etc/network/interfaces’
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ? Your options are:
Y or I : install the package maintainer’s version
N or O : keep your currently-installed version
D : show the differences between the versions
Z : background this process to examine the situation
The default action is to keep your current version.
*** interfaces (Y/I/N/O/D/Z) [default=N] ? N”

OK - good to know.

Thanks. It’s good to know the ‘safe’ method, and this will form part of the wiki entry later on, so people aren’t left with broken networking when attempting alpha instructions.

1 Like

Yes. Whonix 14 is really not ready. Not even for testers. So sandboxes
Tor Browser has to wait unfortunately.


Testing on Debian-8 and pointing to system tor (sys-whonix), sandboxed-tor-browser and the extra step of sudo umount /proc/xen successfully:

  • detects system tor process;
  • downloads Tor; and
  • verifies it correctly.

The mounting error message disappears, but we now run into:

launch: Connecting to the Tor network.
tor: setsid
tor: : Function not implemented
launch: Failing with error: tor: timeout waiting for the control port

The same problem occurs if using sandboxed-tor-browser by just pointing to sys-firewall as the netVM in the system instead. Not clear why, since the bundle ‘should just work’ in that instance right?

By the way, this is with the only dependency installed being bubblewrap and nothing else.

So, we can remove golang, libseccomp2 and libseccomp-dev dependences from the wiki. Also, gnome-themes-standard and gnome-themes-standard-data seem to be already installed on both the Debian and Whonix templates, so that step can be removed too.

I wonder whether a Whonix-WS Template could have just the control-port-filter-python package installed and not the whole Whonix-14 upgrade as an intermediate try? Probably not i.e. depending on a host of other things already broken.

Let me know if there’s anything else I should try.

1 Like

Unfortunately backporting that package to Whonix 13 is not so simple, because multiple components are involved. (Also whonix-gw-firewall, anon-gw-anonymiznizer-config…)