Onionshare Secure File Sharing Over Tor Network Setup

OnionShare uses Tor hidden services to enable direct, peer-to-peer file sharing that exposes neither your IP address nor any files to third-party servers, making it ideal for journalists, whistleblowers, and anyone sharing sensitive data. Install Tor and OnionShare via your package manager or Homebrew, then use the CLI to select files, start sharing, and securely distribute the temporary .onion URL to recipients. This guide covers complete setup, CLI automation, advanced usage patterns, and security best practices for developers and high-security environments.

Prerequisites and Initial Setup

Before installing OnionShare, ensure you have a working Tor installation. Most Linux distributions include Tor in their repositories, but for the latest stable version, add the Tor Project’s repository:

# Debian/Ubuntu
sudo apt update
sudo apt install tor

# Verify Tor is running
tor --version

On macOS, install Tor via Homebrew:

brew install tor
brew services start tor

Windows users can download the Tor Browser bundle, which includes the Tor daemon needed for OnionShare to function.

Installing OnionShare

OnionShare provides both GUI and CLI versions. For server environments and automation, install the CLI version:

# Install via pip (requires Python 3.7+)
pip install onionshare-cli

# Verify installation
onionshare-cli --version

For desktop environments, download the appropriate package from the official GitHub repository:

# Example: Download latest Linux release
wget $(curl -s https://api.github.com/repos/micahflee/onionshare/releases/latest | grep -o "https://.*OnionShare.*\.AppImage" | head -1)
chmod +x OnionShare-*.AppImage

Understanding the Tor Network Connection

OnionShare operates by creating a temporary Tor hidden service that points to files or directories on your local machine. When you start a sharing session, the tool generates a unique .onion URL valid only for that transfer. The recipient connects through the Tor network, establishing an end-to-end encrypted tunnel directly to your machine.

This architecture provides several security advantages over traditional file sharing:

No intermediary servers store your data
Your IP address remains hidden from the recipient
The transfer metadata is protected by Tor’s circuit architecture
Files transfer directly between endpoints

Start a simple file share using the CLI:

# Share a single file
onionshare-cli --verbose /path/to/document.pdf

# Share multiple files
onionshare-cli --verbose /path/to/file1.txt /path/to/file2.zip

# Share an entire directory
onionshare-cli --verbose /path/to/folder/

The CLI outputs a unique URL similar to http://abcd1234567890.onion/. Share this URL with your recipient through a secure channel (Signal, encrypted email, or面对面传递). The connection remains active until either the recipient completes the download or you terminate the process.

Command-Line Options for Power Users

OnionShare CLI offers numerous options for controlling transfer behavior:

# Auto-shutdown after successful transfer
onionshare-cli --auto-shutdown /path/to/file

# Set a custom port
onionshare-cli --port 12345 /path/to/file

# Enable persistent URL (reusable after restart)
onionshare-cli --persistent /path/to/folder

# Require password protection
onionshare-cli --password "your-secure-password" /path/to/file

# Limit download count
onionshare-cli --download-limit 5 /path/to/file

# Receive files instead of sending
onionshare-cli --receive /path/to/upload/directory

The --receive mode is particularly useful for secure document collection. Recipients upload files directly to your machine through Tor, eliminating the need for third-party file upload services.

Automating OnionShare in Scripts

For regular file sharing workflows, integrate OnionShare into shell scripts:

#!/bin/bash
# secure-share.sh - Automated secure file sharing

FILE="$1"
NOTIFY_URL="$2"  # Webhook or notification service

# Generate share URL with auto-shutdown
SHARE_URL=$(onionshare-cli --auto-shutdown --verbose "$FILE" 2>&1 | \
    grep -oP 'http://[a-z2-7]{56}.onion/\S+' | head -1)

if [ -n "$SHARE_URL" ]; then
    # Send notification with share URL
    curl -X POST "$NOTIFY_URL" -d "{\"url\": \"$SHARE_URL\"}"
    echo "Share URL: $SHARE_URL"
else
    echo "Failed to create share"
    exit 1
fi

Schedule recurring shares using cron:

# Edit crontab
crontab -e

# Add scheduled share (every day at 2 AM)
0 2 * * * /usr/local/bin/secure-share.sh /backup/daily.tar.gz https://hooks.example.com/notify

Security Considerations

While OnionShare provides strong anonymity guarantees, follow these best practices:

Network Isolation: Consider running OnionShare from an isolated network namespace or VPN to prevent IP leaks through non-Tor traffic:

# Create network namespace for OnionShare
sudo ip netns add onionshare
sudo ip link add veth0 type veth peer name veth1
sudo ip link set veth1 netns onionshare

File Metadata Stripping: Remove metadata from files before sharing:

# Remove EXIF and other metadata
exiftool -all= document.pdf
# Or use mat2 for comprehensive metadata removal
pip install mat2
mat2 document.pdf

Verification: Generate checksums for shared files to ensure integrity:

# Generate SHA256 checksum
sha256sum /path/to/file > file.sha256

# Share both files via OnionShare
onionshare-cli /path/to/file /path/to/file.sha256

Troubleshooting Common Issues

Connection failures typically stem from Tor configuration problems. Verify your Tor daemon is running and accessible:

# Check Tor status
systemctl status tor

# Test Tor connectivity
curl --socks5 localhost:9050 https://check.torproject.org/api/ip

If OnionShare fails to start, examine the verbose output:

onionshare-cli --verbose --debug /path/to/file

For persistent sharing issues, ensure the data directory has proper permissions:

mkdir -p ~/.local/share/onionshare
chmod 700 ~/.local/share/onionshare

Advanced: Tor Daemon Integration

For high-availability setups, integrate with a persistent Tor daemon rather than relying on OnionShare’s built-in Tor process:

# Configure Tor to allow control connections
# Add to /etc/tor/torrc:
ControlPort 9051
CookieAuthentication 1

# Restart Tor
sudo systemctl restart tor

# Run OnionShare using system Tor
onionshare-cli --tor-control-port 9051 --use-system-tor /path/to/file

This approach provides better resource management for servers handling multiple concurrent shares.

Built by theluckystrike — More at zovo.one