OnionShare Advanced Guide: File Sharing, Chat, and Hosting on Tor

OnionShare 2.x provides four modes. Share mode: creates a .onion URL for downloading specific files or folders. Recipients access the URL in Tor Browser and download the files. After the first download (or a configured time), the service shuts down automatically. Receive mode: creates a .onion URL where anyone who visits can upload files to your computer. No registration required - visitors upload anonymously. Used for anonymous tip submission and document collection. Website mode: serves a folder of HTML/CSS/JavaScript files as a .onion hidden service. Creates a .onion website instantly without server configuration. Chat mode: creates an encrypted, anonymous chat room accessible via a .onion URL. Participants join anonymously and communicate in real time. No message history is stored server-side. Each mode can be configured for persistence (fixed .onion address) or ephemeral (new address each time).

Persistent mode saves the hidden service private key so the .onion address remains the same across sessions. Enable in OnionShare: Settings > Persistent service enabled, or via CLI: onionshare --persistent /path/to/persistent.json. The persistent.json file stores the Ed25519 private key - back this up securely, as losing it means losing the .onion address. Use cases: a journalist's permanent document submission URL shared in their published articles (receive mode, persistent), a community file repository accessible at the same .onion for months (share mode, persistent), and a permanent .onion website for ongoing content (website mode, persistent). Security consideration: persistent mode means the same key is used indefinitely - rotate the key annually by deleting the persistent.json and creating a new persistent service, notifying your contacts of the new address through authenticated channels.

Receive mode turns OnionShare into an anonymous document submission endpoint. Configure: select Receive mode, optionally set a custom description for submitters, enable Allow public uploads (anyone with URL can submit), disable Disable receiving when unattended (keeps service running without user present). Each submission appears as a dated folder in OnionShare's Downloads directory. Submitters see a web interface with a file upload form and optional text message field. They never need to register or provide any identity. For journalists: publish the receive mode .onion URL in articles as a secure contact point. For organizations: maintain the receive service as a persistent hidden service. For higher security (true SecureDrop-equivalent): process received files on an air-gapped computer - copy them to USB, physically transfer to the isolated machine, and analyze without internet access to prevent any malware in received files from communicating.

OnionShare provides a Python API enabling integration into custom security workflows. Install: pip install onionshare-cli. CLI usage: onionshare --mode share myfile.pdf (share a file), onionshare --mode receive --persistent /tmp/persist.json (start a persistent receive service). Python API: from onionshare import OnionShare, OnionShareSettings; settings = OnionShareSettings(); o = OnionShare(settings); o.start_onion_service(). For automating anonymous file delivery as part of a pipeline: a script that shares the output of a security scan report via OnionShare and logs the .onion URL for the recipient. For automated receive endpoint monitoring: a cron job that checks the receive directory for new submissions and sends an encrypted notification via Tor-routed email. OnionShare's web interface code is accessible for customization - replace the default receive form with a custom HTML form matching your organization's SecureDrop workflow.

OnionShare's security depends on keeping the .onion URL secret: anyone with the URL can access the service. For receive mode: the URL is the only access control - share it only through encrypted channels. For public receive services (published in articles): anyone can submit, creating moderation overhead (spam, malicious files). Use a receive password (OnionShare private key + password parameter) to restrict who can submit if the URL will be public. File security: files received via OnionShare may contain malware. Always open received files in a sandbox (Dangerzone converts PDFs and documents to safe versions, Tails OS's isolation, or a dedicated offline analysis VM). OnionShare does not scan files. For the chat mode: messages exist only in memory and are not logged by OnionShare. If a participant's device is compromised, message content on that device is exposed. The .onion chat URL should be shared only with intended participants.