Tor Browser Sandbox (Linux Alpha) - Coming Soon


Interesting points from the Tor Project’s ‘Yawning Angel’ are highlighted below.

Once Mozilla has finished sandboxing for content, media and plugin processes (Firefox 52/53 in Linux?) and we have this application level sandbox for Tor browser running in combination, we’ll all be a lot safer from illegal, wide-spread hacking undertaken by state-level adversaries (no doubt already in play for some time with governments worldwide).

Better yet, your Chrome/Chromium buddies can no longer claim superiority status with sandboxing! :wink:

This should also solve the sandboxing discussion being held elsewhere in the forums, revolving around Firejail as an option.

Presumably Whonix will be an early adopter of Yawning’s alpha sandbox in the testing repos come December, or will update the docs to note how it can be applied easily, since most Whonix users will want it.


What is a sandbox?

It’s a separate environment from the rest of your computer where you run untrusted programs. We’re running Tor Browser. The idea is that exploits targeting Tor Browser are trapped inside the sandbox and can’t get out and mess with the rest of your computer or deanonymize you.

The amount of information Tor Browser will learn about your computer, and thereby you, will be limited. For example, the sandbox will hide things like your files, and real IP and MAC addresses from Tor Browser.

How will the sandbox help users?

It should make Tor a lot safer for users. We know there are people who try to de-anonymize Tor users by exploiting Firefox. Having Tor Browser run in a sandbox makes their life a lot harder.

Which operating system will the sandbox support?

We need a sandbox for Linux, OSX, and Windows. I’m working on the Linux one. The Tor browser team is looking at OSX. In the future we’d like to do Windows.

Why are you doing this?

It’s an interesting technical challenge, and in the light of recent events like The FBI’s Quiet Plan to Begin Mass Hacking, defending users against malicious attackers at the application layer is incredibly important.

When will the sandbox be available to users?

This is experimental. Right now I have something that works on my laptop. It is not user friendly at all. It’s a functional prototype. By the end of the year it will be available in alpha form for early adopters to experiment with.

Mozilla is also working on something like this, right?

Mozilla is working primarily on efforts to sandbox the content, media and plugin processes (roughly a per-tab sandbox).
In our version, the entire browser is running in a sandbox.

Both projects in the long run should work to complement each other, since both are a good idea.

firejail / seccomp / More Options for Program Containment
Hardening Qubes-Whonix

I hope it will still be compatible with the Whonix split model.


For tracking purposes, see Tor project ticket #20352:


Of note:

Preliminary builds for testing the TBB are available from:



Yawning has apparently had people test this on:

  • Arch Linux (amd64)
  • Debian stable (amd64/x86)
  • Fedora 24/25 (amd64)
  • OpenSuse Tumbleweed (amd64)

Packages (runtime dependencies) required for this include those shipping with Debian stable. Minimum:

  • libx11-dev (The calls used have always been there, and always will)
  • Gtk+ 3.14 - Build assumes this, see the Makefile
  • libseccomp2 (2.1.1, 2.2.3 in backports)

I’d love to see Qubes-Whonix running with a sandboxed Tor browser & coldhacka’s GrSec templates across the board this year.


Also note Tor Project tickets: 20773 -> 20783 regarding possible implementation issues in Whonix.


Warnings for future Whonix users should include a statement like:

The sandboxed Tor browser is an alpha release and will probably break many things in the initial version. This includes, but is not limited to:

  • foreign language support;
  • meek and obs4 transports;
  • normal ‘shuffling’ of the ordering of specified internal bridges;
  • ability of the user to open the downloads folder (and probably others) due to container restrictions on /usr/bin; and
  • other unspecified objects.

Of interest for possible future Whonix integration, Tor tickets suggest that:

  • containers require the mounting of /proc (but this will be removed in the future);
  • Tor browser is forced to use an AF_LOCAL socket for the control and socks ports; and
  • permissions, layout and updated logic require the user profile (profile.default) is stored and used under the addons/prefs/etc folder (user data storage in the browser directory will be later removed).

No idea if this will be possible in the Whonix split-model, but I hope so.



This should answer all your questions regarding compatability with Whonix. Key points extracted for you:


Code: ​https://gitweb.torproject.org/tor-browser/sandboxed-tor-browser.git/



Building sandboxed-tor-browser requires:

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


Running sandboxed-tor-browser requires:

A modern Linux system on x86/x86_64 architecture (x86_64 STRONGLY preferred).
bubblewrap >= 0.1.3 (​https://github.com/projectatomic/bubblewrap).
libseccomp2 >= 2.2.1 (x86 only, x86_64 does not require this).
Gtk+ >= 3.14.0
(Optional) PulseAudio 

Where do I get bubblewrap for my distribution?
Distribution Where
Arch Linux ​https://aur.archlinux.org/packages/bubblewrap-git/
Debian (jessie) ​https://packages.debian.org/jessie-backports/admin/bubblewrap
Debian (stretch) ​https://packages.debian.org/stretch/bubblewrap
Fedora ​https://admin.fedoraproject.org/pkgdb/package/rpms/bubblewrap/
Ubuntu No sufficiently recent version is available, complain to Canonical.

How do I make this use a system tor instance?

Using sandboxed-tor-browser in this way is not recommended.

TOR_CONTROL_PORT=9051 sandboxed-tor-browser

TOR_CONTROL_PORT=tcp:// sandboxed-tor-browser

TOR_CONTROL_PORT=unix:///var/run/tor/control sandboxed-tor-browser


A user interface based on Gtk+ is provided to control installing/updating Tor Browser and to assist in configuring the tor daemon and sandbox.

Gtk+3.0 was used despite Tor Browser linking against 2.0 to avoid the need for a future migration.

Files are placed in accordance with the ​XDG Base Directory specification, honoring the appropriate overrides.

Config: ~/.config/sandboxed-tor-browser/
Bundle: ~/.local/share/sandboxed-tor-browser/tor-browser
Tor DataDir: ~/.local/share/sandboxed-tor-browser/tor/
Runtime files (eg: sockets): /var/run/$UID/sandboxed-tor-browser/ 


sandboxed-tor-browser includes the capability to download and install the latest version of Tor Browser.

Supports all of the channels and locales for a given architecture. 
Supports doing the download over tor, assuming a system tor instance is present, and the TOR_CONTROL_PORT env var is set. 
Also downloads the PGP signature of the bundle, and verifies it prior to installation with a hardcoded copy of the PGP key. 
Modifies the bundle configuration post-install via writing out a set of configuration files using the ​Firefox Enterprise Deployment infrastructure. 
    This is needed so that the built in auto updater, and addon updating can be disabled, as the former is handled by sandboxed-tor-browser and the latter will not work by default due to filesystem permissions in the sandbox container.


sandboxed-tor-browser handles keeping the installed bundle up to date, as the bundle directory is mounted read-only inside the firefox container while the browser is actually running, precluding the ability to use the built in updater.

Checks and downloads updates over tor, launching tor in a container if required. Never uses the clear net for either. 
Checks once at launch, as long as the last launch was 6 hours prior. 
Independently validates the MAR signature prior to updating, with hardcoded copies of the signing keys. 
Supports both full and incremental updates, favoring incremental. 
Updates are done in a container with no network access, X11, or other things that are part of the firefox and tor containers. 
Re-installs the config overrides after each update. 

tor daemon interface

sandboxed-tor-browser can either use an existing tor daemon, or launch one in a sandbox container, and is responsible for routing traffic between the tor and firefox sandbox containers (or the system tor and the firefox container).

Interface to the system tor instance if one is configured. 
Launches the tor daemon in a container with a auto-generated torrc based on the user configuration. 
A SOCKS5 server that firefox talks to, that rewrites the SOCKS authentication (needed to isolate circuit/stream status information visible to the firefox process via the Tor Control Port). 
A filtering Tor Control Port that firefox talks to. This provides the minimum subset of events/commands required for "New Identity" and (optionally, only if enabled) the circuit display to function. 
    Due to the re-writing of SOCKS5 authentication info, even if a system Tor is used, the firefox process never sees circuits or streams it is not responsible for.
When sandboxed-tor-browser launches the tor, a SOCKS5 pass-through proxy is provided at the traditional address ( so that the user can use other applications with the sandboxed tor daemon (nb: Some weirdness with torsocks and the pass-through proxy, needs investigation.). 

Sandbox container launcher

sandboxed-tor-browser launches the various sandbox containers by fork() and exec()ing bubblewrap and passing it various arguments and static assets over pipes.

Each container is different, and will be describe in a separate section. The interface code also includes:

A seeccomp rule compiler, that accepts rules in ​https://github.com/twtiger/gosecco gosecco format, that produces bpf output. The actual compiler depends on architecture, x86_64 uses gosecco, i386 uses libseccomp2. 
A dynamic linker cache parser (/etc/ld.so.conf) along with routines used to enumerate the libraries required from the host system inside the container for the binaries that are to be executed. 
A ~/.Xauthority parser and generator, so that only the current target $DSISPLAY is exposed in the container. 
Other misc routines for handling gtk+, PulseAudio, and other things. 

Other notes:

  • Circuit display is disabled;
  • Users will not be able to see files e.g. those downloaded etc (by design);
  • Fonts are limited to a minimal set;
  • Getting sound to work e.g. Pulseaudio requires sandbox config enabling;
  • “Check for Tor Browser Update” will not work manually;
  • Extra addons cannot be added without changes to sandbox config (for good reason);
  • Tor Browser torrc cannot be edited (tor daemon launches its own torrc);
  • Plug-ins will not work e.g. Flash, Silverlight etc (by design); and
  • All relevant Tor tickets can be found in this document at the bottom.


Hmm. I think we’ll need clarification on this point. (Emphasis added to reflect original emphasis :slight_smile: )


Asked about that:



The sandboxing app now available apparently works with default TBB & alpha and hardened versions. Do you think we safely run this in the Whonix-WS? Or will this require some Whonix tinkering - I expect so due to system tor settings required. I am happy to be your guinea pig for this as well.


On December 14th, 2016 Anonymous said:

Is the sandboxing work integrated into this version? Or is that only for the 6.5a6 (non-hardened) series?

On December 14th, 2016 yawning said:

The sandboxing stuff is a separate component and will work with any one of “release”, “alpha” or “hardened”, because the first time you run the sandboxing app, it will ask you which one you want to use.

That said, sandboxed + “hardened” is the least tested combination, because running the hardened bundle involves using a VM or a reboot for me, but it should work.

See also -> https://lists.torproject.org/pipermail/tor-dev/2016-December/011753.html

Of interest:


  • A Gtk+3 based UI for downloading/installing/updating Tor Browser, configuring tor, and launching the sandboxed browser. Think tor-browser-launcher, that happens to run Tor Browser in a bunch of containers.
  • Linux seccomp-bpf + namespace based containers for Tor Browser, that attempts to prevent/mitigate exploits and reduce the amount of personally identifiable information to a minimum, centered around bubblewrap (runtime dependency).

Known system incompatibilities:

  • 64 bit kernel, 32 bit userland is not supported.
  • X32 (x86_64 with 32 bit pointers) is not supported. If you have to ask what this is, and how it’s different from normal 32 bit x86, you don’t have it.
  • Systems that do not store the dynamic linker/loader cache in /etc/ld.so.cache in glibc 2.2 format are not supported.
  • Ubuntu does not have a sufficiently recent bubblewrap package available for any current release, up to and including yakkety (16.10). The package that is available in universe SHOULD NOT be installed, and WILL NOT work.


  • On systems where gstreamer libraries are pulled in as part of the base firefox runtime dependencies, the libraries can find their way into the sandbox without the need for explicit user intervention, if “Extra Audio/Video Codecs” is enabled in the sandbox configuration.

As far as I am aware, and on the systems I have tested, none of the modern distributions have system libraries built this way. If the sandbox manages to launch Tor Browser with the option disabled, you are not affected by this.


Thanks Yawning!

I also look forward to the binaries that are coming this week. I imagine there will be some sharp edges for folks whose Linux distro doesn’t easily come with the right version of bubblewrap – so it would be great if people here could help us identify and resolve those sharp edges.

In the meantime, for those like me who are itching to get it working asap, and don’t mind installing a few more debs, here are the instructions I wrote up for Jessie users – they are quite similar to the instructions Yawning put on https://git.schwanenlied.me/yawning/sandboxed-tor-browser/wiki, but a little bit more explicit in some places so it’s harder to get lost:

Do steps 1-3 as root:

  1. “apt-get install build-essential git libx11-dev libgtk-3-dev”
  1. Setup the system to be able to install backports: add
    "deb http://httpredir.debian.org/debian jessie-backports main" to your /etc/apt/sources.list file, then do “apt-get update”
  1. Install golang and bubblewrap and libseccomp from backports: “apt-get -t jessie-backports install golang bubblewrap libseccomp2 libseccomp-dev”

Do steps 4-9 as the user that will be running Sandboxed Tor Browser:

  1. Set GOPATH:
    “export GOPATH=~/.local/go”
  1. Install gb:
    “go get github.com/constabulary/gb/…”
  1. Add the directory containing the gb binary to your PATH:
    “export PATH=$PATH:~/.local/go/bin”
  1. Clone the repo:
    “git clone https://git.torproject.org/tor-browser/sandboxed-tor-browser.git
  1. Compile it:
    “cd sandboxed-tor-browser; make”
  1. Run it:

It will put its stuff in your ~/.local/share/sandboxed-tor-browser/

Also, see the updated sandbox wiki which has changed a bit in recent times:



look into Sandboxed Tor Browser


Please add these instructions to the wiki.


Add “unfinished” on top. From there I try to fill in any gaps. If we succeed fine, if not, it’s a good start for anyone to pick up from there.

failed to initialize user interface: open /home/user/.local/share/sandboxed-tor-browser/tor-browser/Browser/defaults/pref/autoconfig.js:

Most likely won’t run in Whonix 13 since sandboxed-tor-browser requires Tor cookie control protocol authentication. Most likely requires a newer version of control-port-filter-python which equals upgrading to Whonix 14 developers-only as per https://www.whonix.org/wiki/Dev/Control_Port_Filter_Proxy#tor-controlport-filter_by_Tails.


Great that this is on the radar!

Noting location of binaries for testers. Tor Browser Sandbox Binaries (32-bit and 64-bit) v 0.0.2 are available here:


PS You know you can take Christmas Day off :wink:


Using the binaries is a much better. Therefore no need to verify sources from git and no need to care if go get is actually secure.

So from Do steps 4-9 as the user that will be running Sandboxed Tor Browser: probably all can be skipped.

Also build dependencies do not need to be installed. The the runtime dependencies from backports will be required.

Just download, verify, unzip, cd sandbox, ./sandboxed-tor-browser.

./sandboxed-tor-browser is apparently also a Tor Browser downloader similar to tb-updater / torbrowser-launcher.

Doesn’t work for me yet. Reported a bug upstream.

firefox: Can't mount proc on /newroot/proc:

sandboxed-tor-browser config auto detected system Tor, so if you are feeling adventerious and want to upgrade to Whonix 14 developers-only, feel free to try for yourself.


Looks like no help is forthcoming for Bug 21076:


I don’t see myself being able to reproduce this to debug it. If there’s root cause diagnosis of why this happens, or patches that would be helpful. I also don’t have the time to make all the bits that talk to the control port play nice with something that is out of spec.

So, the Whonix work-around step can be (somewhere):

Testers may find the sandboxed-tor-browser fails to start on the first or second try, due to a broken system control port. The workaround is to run:

rm -r .config/sandboxed-tor-browser

Re: Bug 21077


Yawning has replied that it relates to the Jessie Bubblewrap version?

This looks like bubblewrap being broken on whatever platform this is. If that’s the case, then there isn’t much I can do about it.

What does bwrap --ro-bind / / --proc /proc --dev /dev /bin/bash say.

You said the system tor process is automatically detected. Didn’t you have to make manual config changes to use the system tor process with this info from Yawning’s wiki?

How do I make this use a system tor instance?

Using sandboxed-tor-browser in this way is not recommended.

TOR_CONTROL_PORT=9051 sandboxed-tor-browser

TOR_CONTROL_PORT=tcp:// sandboxed-tor-browser

TOR_CONTROL_PORT=unix:///var/run/tor/control sandboxed-tor-browser

Let me try and summarise correct steps required for this sandboxing testing, check with you, then run it in a cloned template of Whonix-WS which is upgraded to Whonix 14 dev work.


No, because TOR_CONTROL_PORT=9151 already is an environment variable.

You can check that by running:

env | grep TOR

Btw can also be interesting to see all environment variables.


Setting TOR_CONTROL_PORT=9151 might be considered a Whonix bug at some point. (When the Tor Browser 5.0x series are deprecated and 5.5x series requiring SocksSocket. For now TOR_CONTROL_PORT=9151 is required to stay compatible with Tor Browser 5.0x series.

  • TOR_CONTROL_PORT=9151 could be in conflict with
  • TOR_CONTROL_IPC_PATH=/var/run/anon-ws-disable-stacked-tor/

TOR_CONTROL_IPC_PATH=/var/run/anon-ws-disable-stacked-tor/ works with Tor Browser 5.5x series. At some point TOR_CONTROL_PORT=9151 might break Tor Browser (when TCP gets removed from Tor Browser). The bug here might be sandboxed-tor-browser support
TOR_CONTROL_PORT=unix:///var/run/tor/control sandboxed-tor-browser vs leaving that to TOR_CONTROL_IPC_PATH.


Same startup issue on the following platforms.

  • Qubes Debian amd64 jessie TemplateBased AppVM (with golang bubblewrap libseccomp2 libseccomp-dev from jessie-backports)
  • Qubes Debian amd64 stretch TemplateBased AppVM (with golang bubblewrap libseccomp2 libseccomp-dev)

reported here:

Can you try in a Non-Qubes Debian VM?


Works for me in a Non-Qubes Debian jessie VM (with the packages from jessie-backports).



As per https://trac.torproject.org/projects/tor/ticket/21048 also the following dependencies need to be installed.

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

Whonix VirtualBox:

works out of the box. Network settings are auto detected as system Tor just fine. No need to configure network settings. Just start it using:


(i386 version.) (amd64 version / Tor Browser hardened has to wait until Non-Qubes-Whonix 64 bit downloadable images are available. [Status of Whonix 32 bit vs 64 bit]



Sorry, I took the rest of Christmas day off!

Well, your instructions are clear for getting this working in non-Qubes-Whonix, so I can write something up for that and check with you before editing the wiki stub.

There is something obviously wrong in the Qubes-Whonix environment though, so I think we can just note that this is ‘blocked’ pending resolution of Qubes Issue #2540.

This is a real bummer, because with over 600 issues, this may not be solved anytime soon. Or, bubblewrap may have some incompatibility with the Qubes environment.

Thus, Qubes-Whonix users may need to resort to the inferior Firejail as an interim sandboxing work-around, until instructions in that other thread is sorted out and tested.