From Whonix

OnionShare Logo


OnionShare is an open source program that allows users to share/receive files, host a website or chat anonymously utilizing the Tor network. [1] OnionShare is installed by default as of Whonix ™ 15. The OnionShare wiki succinctly describes the design: [2]

Web servers are started locally on your computer and made accessible to other people as Tor onion services [archive].

By default, OnionShare web addresses are protected with a random password. A typical OnionShare address might look something like this:

http://onionshare:constrict-purity@by4im3ir5nsvygprmjq74xwplrkdgt44qmeapxawwikxacmr3dqzyjad.onion [archive]

You’re responsible for securely sharing that URL using a communication channel of your choice like in an encrypted chat message, or using something less secure like unencrypted e-mail, depending on your threat model [archive].

The people you send the URL to then copy and paste it into their Tor Browser [archive] to access the OnionShare service.

As of OnionShare version 2.0 it is also possible to run the program in Receive mode. This means you can receive files via OnionShare after they are uploaded by Tor Browser users; this is a sort of 'SecureDrop Lite' or personal dropbox. Version 2.2 of OnionShare also permits the easy hosting of anonymous websites [archive]:

In addition to the “Share Files” and “Receive Files” tabs, OnionShare 2.2 introduces the “Publish Website” tab. You drag all of the files that make up your website into the OnionShare window and click “Start sharing.” It will start a web server to host your static website and give you a .onion URL. This website is only accessible from the Tor network, so people will need Tor Browser to visit it. People who visit your website will have no idea who you are – they won’t have access to your IP address, and they won’t know your identity or your location. And, so long as your website visitors are able to access the Tor network, the website can’t be censored.

Version 2.3 of OnionShare allows users to share/receive files, host websites or chat anonymously at the same time using a tabs feature. The secure, ephemeral and anonymous chat feature is particularly useful since it does not require account creation, is encrypted end-to-end and reduces the risk of messages being stored locally: [3]

Now when you open OnionShare you are presented with a blank tab that lets you choose between sharing files, receiving files, hosting a website, or chatting anonymous. You can have as many tabs open as you want at a time, and you can easily save tabs (that's what the purple thumbtack in the tab bar means) so that if you quit OnionShare and open it again later, these services can start back up with the same OnionShare addresses. ... Another major new feature is chat. You start a chat service, it gives you an OnionShare address, and then you send this address to everyone who is invited to the chat room (using an encrypted messaging app like Signal, for example). Then everyone loads this address in a Tor Browser, makes up a name to go by, and can have a completely private conversation.

As OnionShare is an actively developed project, it is recommended to refer to official documentation [archive] for the latest features and information before use. Advanced users should also consider additional features [archive] like saving of tabs, turning off passwords, scheduled start/stop times, command line operations and legacy addresses.


Info OnionShare is no longer installed by default. [4] Debian buster -- which Whonix ™ 15 is based on -- packages version 1.3.2. This only supports legacy v2 onions which are being phased out and deprecated on July 15th, 2021 [archive]; this is a known security risk. [5] [6] [7]

OnionShare will likely be included as part of the Whonix ™ 16 release, as Debian bullseye packages version 2.2-3 which utilizes v3 onions. [8] In the interim, the Flatpak installation method is recommended as a suitable workaround.

Flatpak OnionShare Installation[edit]

Info It is recommended to create a separate Whonix-Workstation ™ (Qubes-Whonix ™: anon-onionshare AppVM). [9] The reason is the OnionShare installation will be persistent in this configuration and it is also best practice to separate anonymous activities of a different nature in distinct VMs (AppVMs). [10]

1. Install the flatpak package.

Info Platform specific.

Install flatpak.

1. Update the package lists.

sudo apt-get update

2. Upgrade the system.

sudo apt-get dist-upgrade

3. Install the flatpak package.

Using apt-get command line parameter --no-install-recommends is in most cases optional.

sudo apt-get install --no-install-recommends flatpak

The procedure of installing flatpak is complete.

2. Platform specific reboot required.

  • Qubes-Whonix ™ users: Must also shutdown the whonix-ws-15 TemplateVM after flatpak is installed, and restart the anon-onionshare AppVM.
  • Non-Qubes-Whonix ™ users: No reboot required.

3. Add flathub repository. [11]

Non-Qubes-Whonix ™:

flatpak remote-add --if-not-exists flathub

Qubes-Whonix ™ (in the whonix-ws-15 AppVM):

flatpak --user remote-add --if-not-exists flathub

4. Install the flatpak onionshare package.

Non-Qubes-Whonix ™:

flatpak install flathub org.onionshare.onionshare

Qubes-Whonix ™ (in the whonix-ws-15 AppVM):

flatpak --user install flathub org.onionshare.onionshare

5. Done.

The procedure of installing onionshare is complete.

6. Upgrades notice.

Note: this will not keep the relevant software up-to-date. Occasionally check if flathub has a later version available and run the last command above to update.

After installation is finished, follow the steps in the Whonix VM Configuration section.

Whonix VM Configuration[edit]

Ambox notice.png This application requires incoming connections through a Tor onion service. Supported Whonix-Gateway ™ modifications are therefore necessary for full functionality; see instructions below.

For better security, consider using Multiple Whonix-Gateway ™ and Multiple Whonix-Workstation ™. In any case, Whonix ™ is the safest choice for running it. [12]

1. Extend the onion-grater whitelist in Whonix-Gateway ™ (sys-whonix).

Extend onion-grater Whitelist

On Whonix-Gateway ™.

Create a new directory. [13] [14]

sudo onion-grater-add 40_onionshare

2. Modify the Whonix-Workstation ™ (anon-onionshare) user firewall settings and reload them.

Modify Whonix-Workstation ™ User Firewall Settings

Note: If no changes have yet been made to Whonix Firewall Settings, then the Whonix User Firewall Settings File /etc/whonix_firewall.d/50_user.conf appears empty (because it does not exist). This is expected.

If using Qubes-Whonix ™, complete these steps.
In Whonix-Workstation ™ AppVM. Make sure folder /usr/local/etc/whonix_firewall.d exists.

sudo mkdir -p /usr/local/etc/whonix_firewall.d

Qubes App Launcher (blue/grey "Q")Whonix-Workstation ™ AppVM (commonly called anon-whonix)Whonix User Firewall Settings

If using a graphical Whonix-Workstation ™, complete these steps.

Start MenuApplicationsSystemUser Firewall Settings

If using a terminal-only Whonix-Workstation ™, complete these steps.

Open /usr/local/etc/whonix_firewall.d/50_user.conf with root rights.

sudoedit /usr/local/etc/whonix_firewall.d/50_user.conf

For more help, press on Expand on the right.

Note: This is for informational purposes only! Do not edit /etc/whonix_firewall.d/30_whonix_workstation_default.conf.

The Whonix Global Firewall Settings File /etc/whonix_firewall.d/30_whonix_workstation_default.conf contains default settings and explanatory comments about their purpose. By default, the file is opened read-only and is not meant to be directly edited. Below, it is recommended to open the file without root rights. The file contains an explanatory comment on how to change firewall settings.

## Please use "/etc/whonix_firewall.d/50_user.conf" for your custom configuration,
## which will override the defaults found here. When Whonix is updated, this
## file may be overwritten.

See also Whonix modular flexible .d style configuration folders.

To view the file, follow these instructions.

If using Qubes-Whonix ™, complete these steps.

Qubes App Launcher (blue/grey "Q")Template: whonix-ws-15Whonix Global Firewall Settings

If using a graphical Whonix-Workstation ™, complete these steps.

Start MenuApplicationsSettingsGlobal Firewall Settings

If using a terminal-only Whonix-Workstation ™, complete these steps.

In Whonix-Workstation ™, open the whonix_firewall configuration file in an editor.

nano /etc/whonix_firewall.d/30_whonix_workstation_default.conf

Add. [15]

EXTERNAL_OPEN_PORTS+=" $(seq 17600 17659) "


Reload Whonix-Workstation ™ Firewall.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Workstation ™ AppVM (commonly named anon-whonix)Reload Whonix Firewall

If you are using a graphical Whonix-Workstation ™, complete the following steps.

Start MenuApplicationsSystemReload Whonix Firewall

If you are using a terminal-only Whonix-Workstation ™, run.

sudo whonix_firewall

Start OnionShare[edit]


If the flatpak version was installed, run.

flatpak run org.onionshare.OnionShare

Figure: First Start of OnionShare v2.3.1 GUI


OnionShare Configuration[edit]

Ambox warning pn.svg.png Do not use the bundled Tor configuration for OnionShare; this would lead to a Tor-over-Tor scenario.

On the first run of OnionShare: [17]

  1. Select the settings button/icon (cog symbol) in the GUI.
  2. Under “How should OnionShare connect to Tor?” choose “Connect using socket file”, and set the socket file to /var/run/tor/control
  3. Under “Tor authentication options” choose “No authentication, or cookie authentication”.

To test OnionShare is running correctly:

  • Click the “Test Tor Settings” button. If all steps were completed correctly, Tor will successfully connect.
  • The GUI should say it supports both ephemeral onion services and stealth onion services.

Figure: OnionShare Settings Window


  • By default, if OnionShare version 2.0 or higher is installed and the system Tor version is version 3.5.7 or greater (as it is in Whonix ™), OnionShare uses next-gen or 'v3' onion addresses by default. These are recognizable by their longer address.

How-to: Use OnionShare[edit]

Once OnionShare has been installed correctly and the Tor check is successful, sharing files anonymously is easy: [18]

You can use OnionShare to send files and folders to people securely and anonymously. Open a share tab, drag in the files and folders you wish to share, and click “Start sharing”.

... When you’re ready to share, click the “Start sharing” button. You can always click “Stop sharing”, or quit OnionShare, immediately taking the website down. You can also click the “↑” icon in the top-right corner to show the history and progress of people downloading files from you.

Now that you have a OnionShare, copy the address and send it to the person you want to receive the files. If the files need to stay secure, or the person is otherwise exposed to danger, use an encrypted messaging app.

That person then must load the address in Tor Browser. After logging in with the random password included in the web address, the files can be downloaded directly from your computer by clicking the “Download Files” link in the corner.

Figure: Select File to Share


Figure: Secret Onion URL for Downloaders


Figure: OnionShare Download with Tor Browser [19]


Later OnionShare versions have significantly improved functionality:

  • Version 2.0 provides a feature called 'Receive Mode'. With this mode, you can start an onion service and allow other users to upload files to you via Tor Browser (rather than Share Mode, in which you share files from your OnionShare to others).
  • Version 2.2 allows the hosting of static HTML websites.
  • Version 2.3 allows users to set up a private, secure chat room that does not require an account and does not log activity.

A complete user guide is available, including advanced topics, hardening options [20] and development documentation; refer to the official website [archive].

Do not change settings without fully understanding their function, otherwise onion addresses might be re-used, shares might be left open even after multiple downloads are performed, and so on.

OnionShare AppArmor Profiles[edit]

AppArmor profiles are available to better contain OnionShare, but they have not yet been tested in Whonix ™. [21] Profile development is reported to be lagging behind the master and development branches of the OnionShare git repository. Therefore, willing testers should be knowledgeable about AppArmor profiles before attempting this procedure.

Advanced users are encouraged to help progress the open OnionShare AppArmor ticket [archive] and help complete this wiki section. Successes or failures can also be reported in the Whonix ™ AppArmor forum [archive].

TODO: Test profiles and expand this section.


  1. [archive]
  2. [archive]
  3. [archive]
  4. [archive]
  5. [archive]
  6. OnionShare Whonix integration development discussion [archive].
  7. Quote The Tor Project: Onion Service version 2 deprecation timeline [archive]:

    Here is our planned deprecation timeline:

    1. September 15th, 2020 0.4.4.x: Tor will start warning onion service operators and clients that v2 is deprecated and will be obsolete in version 0.4.6.

    2. July 15th, 2021 0.4.6.x: Tor will no longer support v2 and support will be removed from the code base.

    3. October 15th, 2021

    We will release new Tor client stable versions for all supported series that will disable v2.

  8. [archive]
  9. To clone the existing anon-whonix in Qubes-Whonix ™: Qube ManagerRight-click on anon-vmSelect "Clone qube"Rename to "anon-onionshare"
  10. Qubes-Whonix ™ users should also consider creating a separate, cloned whonix-ws-15 TemplateVM before installing flatpak.
  11. [archive]
  12. Security considerations:
    • By using Whonix ™, additional protections are in place for greater security.
    • This application requires access to Tor's control protocol.
    • In the Whonix ™ context, Tor's control protocol has dangerous features. The Tor control command GETINFO address reveals the real, external IP of the Tor client.
    • Whonix ™ provides onion-grater, a Tor Control Port Filter Proxy - filtering dangerous Tor Control Port commands.
    • When this application is run inside Whonix ™ with an onion-grater whitelist extension, this will limit application rights to Tor control protocol access only. Non-whitelisted Tor control commands such as GETINFO address are rejected by onion-grater in these circumstances.
    • During the application's normal operations it should not attempt to use dangerous Tor control commands such as GETINFO address. In the event the application or Whonix-Workstation ™ are compromised, this command would be rejected.
    • In comparison, if the application is run on a non-Tor focused operating system like Debian, it will have unlimited access to Tor's control protocol (a less secure configuration).
    • If the (non-)Whonix platform is used to host onion services, then running applications are more vulnerable to attacks against the Tor network compared to when Tor is solely used as a client; see also Onion Services Security.
    In conclusion, Whonix ™ is the safest and correct choice for running this application.
  13. Using /usr/local/etc/onion-grater-merger.d/ because that onion-grater settings folder is persistent in Qubes-Whonix ™ TemplateBased ProxyVMs i.e. Whonix-Gateway ™ (commonly called sys-whonix). Non-Qubes-Whonix ™ users could also utilize /etc/onion-grater-merger.d/. Qubes-Whonix ™ users could also utilize /etc/onion-grater-merger.d/ but then /etc/onion-grater-merger.d/ must be made persistent, which means doing this procedure inside the Whonix-Gateway ™ TemplateVM (commonly called whonix-gw-15) and then restarting the Whonix-Gateway ™ ProxyVM or using bind-dirs [archive]. Both techniques are more complicated than simply using /usr/local/etc/onion-grater-merger.d/, since it is persistent either way. Further, it even allows multiple Whonix-Gateway ™ ProxyVMs based on the same Whonix-Gateway ™ TemplateVM; for example, one Whonix-Gateway ™ ProxyVM extending and relaxing onion-grater's whitelist and the other Whonix-Gateway ™ ProxyVM having the default onion-grater whitelist which is more restrictive.
  14. Previously manual instructions. No longer needed. onion-grater-add automates that.
    sudo mkdir -p /usr/local/etc/onion-grater-merger.d/

    Symlink the onion-grater profile to the onion-grater settings folder.

    sudo ln -s {{{filename_new}}}.yml /usr/local/etc/onion-grater-merger.d/

    Restart onion-grater.

    sudo service onion-grater restart

  15. As per [archive] OnionShare uses ports 17600 to 17659.
  16. Outdated. This only applies if OnionShare was installed from Debian package sources. Launch OnionShare in Whonix-Workstation ™ by either running the command line interface or GUI version.


  17. [archive]
  18. [archive]
  19. [archive]
  20. Such as setting a Shutdown Timer to self-destruct shares if they are not downloaded within an acceptable time window. These topics are beyond the scope of this documentation.
  21. [archive]

Fosshost is sponsors Kicksecure stage server Whonix old logo.png
Fosshost About Advertisements

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

Follow: 1024px-Telegram 2019 Logo.svg.png Iconfinder Apple Mail 2697658.png Twitter.png Facebook.png Rss.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Support: 1024px-Telegram 2019 Logo.svg.png Discourse logo.png Matrix logo.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

Twitter-share-button.png Facebook-share-button.png Telegram-share.png Iconfinder Apple Mail 2697658.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Did you know that Whonix ™ could provide protection against backdoors? See Verifiable Builds. Help is wanted and welcomed.

https link onion link Priority Support | Investors | Professional Support

Whonix | © ENCRYPTED SUPPORT LP | Heckert gnu.big.png Freedom Software / Osi standard logo 0.png Open Source (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.

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.