Dev/Whonix friendly applications best practices

From Whonix

< Dev

config.d support[edit]

Please parse a /etc/your-application.d configuration folder so Linux distributions such as Debian and Whonix ™ can set defaults (such as proxy / stream isolation configuration). Users are of course free to overrule these defaults using the usual configuration files in the user's home folder.

Please parse only configuration files with a file extension such as .conf. This is because graphical editors such as kate create backup files such as file-name~ or apt-get / dpkg creating files such as config-file-name.dpkg-old which would lead to unexpected results.

Stream Isolation[edit]


  • Please use add_onion Tor control protocol command / Tor ephemeral onion services.

ephemeral: Means the onion service will be gone after the Tor control connection is closed. It's however possible and usual to retrieve onion service private key and to restore it at next run.

For example ricochet [archive] by @special [archive] is doing that.

Tor ephemeral onion services are a lot a lot better for Whonix ™ than preconfigued Tor hidden services.

onionshare [archive] by @micahflee [archive] has superb Tails and Whonix ™ support.

Listen Interface[edit]

  • Listen on all interfaces rather than just localhost. (This is required since the incoming onion service connection comes from the network, not from localhost.)
    # In {{project_name}}, listen on instead of (#220)
    if os.path.exists('/usr/share/anon-ws-base-files/workstation'):
        host = ''
        host = ''

Related: Listen Port Convention [archive]

Listen Port[edit]

  • Don't listen on a random local server port.
  • Listen on a specific local server port or port range.
  • Tor VIRTPROT (remote virtual port on the onion service) does not matter.
  • [1]

Tor Settings Autodetection[edit]

  • Auto detect Tor settings through TOR_* environment variables.

In Whonix:


These are unix domain socket files.

Ports would also work but nowadays unix domain socket files are much more advisable since these are less likely to leak.


  • The application should not crash if Tor ControlPort replies something unexpected such as 510 Command filtered.


  • Show an error message if Whonix ™ is detected and seeing 510 Command filtered:

Error talking to the Tor controller.\nIf you're using Whonix ™, check out [archive] to make ProgramName work.


  • Bonus: Make a list of Tor control commands you are using so an onion-grater profile can be written.

See Also[edit]

Forum Discussion[edit] [archive]


    • onionshare uses 17600 - 17659. That is handy, so we can match for it using (176[0-5][0-9]) in the onionshare onion-grater whitelist config [archive].
    • That way onionshare (running inside a compromised workstation) cannot open arbitrary ports on the workstation. For example, not to the real Tor ControlPort and circumvent the filtering. (We use Tor ControlSocket rather than ControlPort now for this reason.) There are no local ports open on Whonix-Gateway ™ besides Tor Socks, DNS and TransPort, but if there was (let's say for example for brltty [archive]), then we don't want connections to it.
    • That allows us to set a limit on how many Tor hidden services (a compromised) workstation can create.
    • It's also useful so users don't have to open all incoming ports in Whonix-Workstation Firewall.

text=Jobs in USA
Jobs in USA

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow: Twitter.png Facebook.png 1280px-Gab text logo.svg.png Iconfinder news 18421.png Rss.png Matrix logo.svg.png 1024px-Telegram 2019 Logo.svg.png Discourse logo.svg Reddit.jpg Diaspora.png Gnusocial.png Mewe.png 500px-Tumblr Wordmark.svg.png Iconfinder youtube 317714.png 200px-Minds logo.svg.png 200px-Mastodon Logotype (Simple).svg.png 200px-LinkedIn Logo 2013.svg.png

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png Monero donate whonix.png United Federation of Planets 1000px.png

Share: Twitter | Facebook

Want to get involved with Whonix ™? Check out our Contribute [archive] page.

https link onion link

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation. Policy of Whonix Website and Whonix Chat and Policy On Nonfreedom Software applies.

Copyright (C) 2012 - 2020 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

Whonix ™ is a derivative of and not affiliated with Debian [archive]. Debian is a registered trademark [archive] owned by Software in the Public Interest, Inc [archive].

Whonix ™ is produced independently from the Tor® [archive] anonymity software and carries no guarantee from The Tor Project [archive] about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint, Contact.