Last updated: March 16, 2026

Set up an OnionShare dead drop by installing the application, creating a receive-only mode, and hosting it as a Tor onion service that accepts file uploads over encrypted channels. Sources access the service via a one-time URL over Tor, submit documents, and disconnect without leaving identifying information. OnionShare never logs IP addresses, doesn’t require accounts, and automatically deletes files after retrieval, creating truly anonymous submission channels for developers and power users protecting sources.

Prerequisites

Before setting up your dead drop, ensure you have:

For a persistent dead drop that remains available around the clock, a VPS is more reliable than a laptop that gets closed or rebooted. DigitalOcean’s $6/month Droplet running Ubuntu 22.04 is sufficient. OnionShare supports headless operation through its CLI, making server deployment practical.

Step 2 - Step-by-Step Setup

  1. Install OnionShare

On macOS with Homebrew:

brew install --cask onionshare

On Linux:

sudo apt install onionshare

On Windows, download the installer from the official website.

For server deployment on a headless Linux VPS, install the CLI package:

sudo apt install onionshare-cli

The CLI version exposes all the same functionality without requiring a graphical desktop environment, essential for running the dead drop on a remote server.

  1. Configure OnionShare for Dead Drop Mode

Launch OnionShare and select “Receive Files” mode. This configures OnionShare as a dead drop where sources can upload files to your server.

In the settings panel, configure these options:

For CLI operation on a server, the equivalent command is:

onionshare-cli --receive --persistent /path/to/config.json --no-autostop-sharing

The --no-autostop-sharing flag keeps the service running indefinitely rather than shutting down after the first upload, critical for an always-on dead drop.

  1. Set Up Receive Options

Configure the receive behavior in the settings:

Maximum file size - 50MB (adjust based on your needs)
Receive length - 0 (unlimited, sources can submit anytime)

You can also add a custom welcome message that sources see when they visit your onion service. Keep this message minimal, instructions to use Tor Browser, an assurance that no logs are kept, and a contact method for questions if needed.

  1. Generate and Secure Your Onion Address

OnionShare generates a unique .onion URL. This address serves as your dead drop location. The application provides two versions:

For a source dead drop, share the long address. Copy this address and store it securely, you cannot recover it if lost.

OnionShare v2.6 and later generates v3 onion addresses by default. These are 56-character addresses (rather than the 16-character v2 addresses) and offer significantly stronger cryptographic security. Verify that your generated address is 56 characters before distributing it to sources. Older versions of OnionShare or Tor may generate v2 addresses, update both to current versions.

  1. Enable Persistent Storage

By default, received files are stored in OnionShare’s temporary directory. Configure a persistent storage location:

  1. Go to Settings → Receive
  2. Set “Save files to” to a dedicated directory
  3. Ensure proper filesystem permissions
mkdir -p ~/OnionShare/drops
chmod 700 ~/OnionShare/drops

On a VPS, consider encrypting the directory where incoming files land using cryptsetup or a LUKS-encrypted volume. This ensures that if the server is seized or imaged, the submitted files cannot be read without your encryption passphrase.

  1. Add Encryption Layer (Optional but Recommended)

For additional security, encrypt files before processing them. Create a simple GPG wrapper:

#!/usr/bin/env python3
import gnupg
import os
from pathlib import Path

class SecureDrop:
    def __init__(self, gpg_home='/path/to/gpg/home'):
        self.gpg = gnupg.GPG(gnupghome=gpg_home)

    def encrypt_file(self, filepath, recipient_keyid):
        with open(filepath, 'rb') as f:
            encrypted = self.gpg.encrypt_file(
                f,
                recipients=[recipient_keyid],
                output=f"{filepath}.gpg"
            )
        return encrypted.ok

Usage
drop = SecureDrop()
drop.encrypt_file('uploaded_file.bin', 'YOUR_KEY_ID')

This ensures that even if someone compromises your server, they cannot read the submitted content without your private GPG key.

A practical workflow - configure a filesystem watcher (inotifywait on Linux) to trigger the GPG encryption script automatically whenever a new file appears in the OnionShare receive directory. This way, submitted files are encrypted within seconds of arrival, minimizing the window during which they exist in plaintext.

Watch for new files and auto-encrypt
inotifywait -m ~/OnionShare/drops -e create |
while read path action file; do
    python3 /usr/local/bin/encrypt-drop.py "$path$file" YOUR_GPG_KEY_ID
    echo "Encrypted - $file at $(date)" >> ~/OnionShare/log.txt
done

Operational Security Considerations

Running a dead drop requires attention to operational security:

Network Isolation

Run OnionShare on an isolated network segment if possible. Consider using a dedicated VPN in addition to Tor to prevent traffic correlation attacks. However, be aware that VPNs introduce a different trust dependency, your VPN provider can see that you are using Tor, which in some threat models is undesirable. For most use cases, Tor alone provides sufficient anonymity for the server-side operator.

File Handling

Create a processing workflow that minimizes exposure:

  1. Download files from OnionShare to an air-gapped machine
  2. Transfer to a secure analysis environment
  3. Wipe the original uploads immediately

For transferring files from the server to an air-gapped workstation, use an encrypted USB drive. Mount the drive, copy the GPG-encrypted files, unmount, then shred the originals on the server:

shred -u ~/OnionShare/drops/original_file.bin

shred overwrites the file data before deletion, making recovery harder on traditional spinning disk drives. On SSDs with wear leveling, shred is less effective, full disk encryption at the volume level is the more reliable protection on SSDs.

Metadata Stripping

Sources should strip metadata from documents before submission. Provide them with tools or instructions:

Using exiftool to strip metadata
exiftool -all= document.pdf
exiftool -all= image.jpg

Consider including a note in your welcome message directing sources to the MAT2 (Metadata Anonymisation Toolkit) tool, which handles a broader range of file formats than exiftool and is available in the Tails OS default installation. Sources using Tails for submission already benefit from Tor integration at the OS level.

Source Instructions

The instructions you provide to sources are part of your security model. Poorly written instructions create risk if sources misunderstand the process. A clear template:

To submit information securely:

1. Download Tor Browser from torproject.org
2. Copy and paste this address into Tor Browser:
   [your-onion-address].onion

3. Follow the on-screen instructions to upload files
4. Use MAT2 or exiftool to strip metadata from documents before uploading

Close Tor Browser after submission to protect your session.
Do not reuse this session for other browsing.

Step 3 - Sharing the Dead Drop Address

When providing the onion address to sources, use multiple channels:

For high-stakes contexts, consider publishing the onion address in a verifiable public location, your organization’s website, a signed keybase post, or a PGP-signed message, so sources can independently verify they have the correct address and not one planted by an adversary.

Troubleshooting Common Issues

Connection Problems

If sources cannot connect to your dead drop:

Check OnionShare’s status from the CLI:

onionshare-cli --receive --verbose

The verbose flag shows Tor circuit establishment progress and will indicate if the onion service descriptor has been published to the Tor network.

Large File Uploads

OnionShare may time out with large files. Instruct sources to:

For archives, 7-Zip with AES-256 encryption adds an additional layer before transit, even if the Tor connection is compromised, the archive content remains protected.

Server Availability

For high-stakes operations, run OnionShare on a VPS with uptime guarantees. Configure automatic restart scripts:

#!/bin/bash
while true; do
    onionshare --receive --persistent ~/OnionShare/config.json
    sleep 5
done

A systemd service unit is more durable than a shell loop for production deployments:

[Unit]
Description=OnionShare Dead Drop
After=network.target tor.service

[Service]
User=onionshare
ExecStart=/usr/bin/onionshare-cli --receive --persistent /home/onionshare/config.json --no-autostop-sharing
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable with systemctl enable --now onionshare-drop. The service restarts automatically on failure and starts at boot, ensuring availability even after VPS reboots or transient errors.

Frequently Asked Questions

How long does it take to set up encrypted dead drop using onionshare?

For a straightforward setup, expect 30 minutes to 2 hours depending on your familiarity with the tools involved. Complex configurations with custom requirements may take longer. Having your credentials and environment ready before starting saves significant time.

What are the most common mistakes to avoid?

The most frequent issues are skipping prerequisite steps, using outdated package versions, and not reading error messages carefully. Follow the steps in order, verify each one works before moving on, and check the official documentation if something behaves unexpectedly.

Do I need prior experience to follow this guide?

Basic familiarity with the relevant tools and command line is helpful but not strictly required. Each step is explained with context. If you get stuck, the official documentation for each tool covers fundamentals that may fill in knowledge gaps.

Is this approach secure enough for production?

The patterns shown here follow standard practices, but production deployments need additional hardening. Add rate limiting, input validation, proper secret management, and monitoring before going live. Consider a security review if your application handles sensitive user data.

Where can I get help if I run into issues?

Start with the official documentation for each tool mentioned. Stack Overflow and GitHub Issues are good next steps for specific error messages. Community forums and Discord servers for the relevant tools often have active members who can help with setup problems.

Related Articles