Skip to content
Klutch.sh Docs

Deploying OnionShare

Introduction

OnionShare is an open-source tool that enables secure and anonymous file sharing, website hosting, and chat functionality over the Tor network. Developed by Micah Lee and the Freedom of the Press Foundation, OnionShare creates temporary onion services that allow users to share files without relying on third-party servers.

When you share files with OnionShare, it starts a web server directly on your device, creates an onion address, and provides a unique URL that recipients can access via Tor Browser. The connection never leaves the Tor network, ensuring privacy and anonymity for both sender and recipient.

Key features of OnionShare include:

  • Anonymous File Sharing: Share files without revealing your identity or location
  • Receive Files: Set up a dropbox for others to send files to you anonymously
  • Website Hosting: Host static websites as Tor onion services
  • Private Chat: Create ephemeral chat rooms accessible only via Tor
  • No Third Parties: Files are shared directly without intermediary servers
  • Encrypted by Default: All traffic is end-to-end encrypted through Tor
  • Auto-Stop Option: Automatically stop sharing after files are downloaded
  • Password Protection: Add passwords to your shares for additional security
  • Cross-Platform: Available for Windows, macOS, Linux, and as a CLI tool

This guide walks through deploying OnionShare CLI on Klutch.sh for server-based file sharing scenarios.

Why Deploy OnionShare on Klutch.sh

Deploying OnionShare on Klutch.sh enables persistent onion services for your organization:

Always-On Sharing: Unlike desktop usage, a server deployment can run OnionShare continuously for persistent file drops or website hosting.

Anonymous Dropboxes: Create always-available anonymous submission systems for whistleblowers or sensitive document receipt.

Persistent Storage: Attach volumes for received files that persist across container restarts.

Resource Allocation: Allocate sufficient resources for Tor relay connections and file handling.

Prerequisites

Before deploying OnionShare on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your deployment
  • Understanding of Tor network and onion services
  • Tor Browser for accessing your onion services

Deploying OnionShare on Klutch.sh

    Create Your Dockerfile

    Create a Dockerfile in your repository:

    FROM python:3.11-slim
    

    # Install Tor and dependencies
    RUN apt-get update && apt-get install -y \
        tor \
        build-essential \
        && rm -rf /var/lib/apt/lists/*
    

    # Install OnionShare CLI
    RUN pip install onionshare-cli
    

    # Create directories
    RUN mkdir -p /data/share /data/receive /var/lib/tor
    

    # Configure Tor
    RUN echo "DataDirectory /var/lib/tor" >> /etc/tor/torrc
    

    # Copy startup script
    COPY start.sh /start.sh
    RUN chmod +x /start.sh
    

    EXPOSE 17600-17650
    

    CMD ["/start.sh"]

    Create Startup Script

    Create start.sh:

    #!/bin/bash
    

    # Start Tor
    service tor start
    

    # Wait for Tor to bootstrap
    sleep 10
    

    # Start OnionShare in receive mode
    onionshare-cli --receive --persistent /data/onionshare.json --data-dir /data/receive

    Push to GitHub

    Commit and push your Dockerfile and startup script to your GitHub repository.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project.

    Create and Configure the App

    Create a new app and connect it to your GitHub repository.

    Configure Traffic

    OnionShare operates over Tor and does not require traditional HTTP ports. Configure internal ports in the range 17600-17650.

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /data50+ GBShared and received files
    /var/lib/tor1 GBTor data directory and keys

    Deploy Your Application

    Click Deploy to build and launch your OnionShare instance.

    Retrieve Your Onion Address

    Check the container logs to find your generated .onion address. With persistent Tor keys, your onion address remains the same across restarts.

    Access via Tor Browser

    Share your .onion address with recipients who can access it using Tor Browser.

Additional Resources