The Problem
Transferring files or hosting temporary web content without exposing the sender’s IP address is difficult for users who lack deep networking expertise. Conventional cloud services leave metadata that can be correlated, and setting up a Tor hidden service manually requires several steps and careful configuration.
What This Does
onionshare provides a ready‑to‑run Python application that creates a Tor hidden service on‑the‑fly, then serves a file, directory, or a simple chat/web page. The CLI implementation lives in cli/onionsharecli/ (e.g., onionsharecli/onion.py, onionsharecli/onionshare.py) and the desktop GUI lives under desktop/onionshare/ with entry point desktop/onionshare/main.py.
The core Tor interaction is encapsulated in cli/onionsharecli/onion.py, which builds a temporary torrc from the templates in cli/onionsharecli/resources/ (e.g., torrctemplate-obfs4). Web‑mode handlers (chatmode.py, receivemode.py, sendbasemode.py, etc.) serve the content via a small Flask‑like server defined in cli/onionsharecli/web/web.py. Static assets and HTML templates for the web UI are stored under cli/onionsharecli/resources/static/ and cli/onionsharecli/resources/templates/.
How To Use It
Setup
The project uses Poetry for dependency management.
Clone the fork
git clone https://github.com/<your‑fork>/onionshare.git cd onionshare/cli
Install dependencies in an isolated environment
poetry install
Poetry reads cli/pyproject.toml and resolves exact versions from cli/poetry.lock. No Dockerfile or Makefile is present, so a container build would require custom scripting.
Configuration
Tor binaries must be on the system PATH; the code expects to launch tor directly. No additional config files are required beyond the built‑in torrctemplate files, which the program copies to a temporary location at runtime.
Running
CLI mode (file share, directory share, chat, website):
poetry run python -m onionsharecli.onionshare --share file <path/to/file>
Typical sub‑commands are implemented in cli/onionsharecli/onionshare.py and parsed by cli/onionsharecli/common.py. The exact flag names are documented in the upstream README but are not hard‑coded in this fork; consult cli/tests/testcli.py for examples.
Desktop GUI:
poetry run python -m onionshare.main
The GUI entry point desktop/onionshare/main.py creates the Qt application defined in desktop/onionshare/mainwindow.py.
Real‑World Use
A security‑conscious journalist could embed the following workflow into a script that automates a one‑time file drop:
#!/usr/bin/env bash FILE=$1 poetry run python -m onionsharecli.onionshare --share file "$FILE" > /tmp/onionurl.txt echo "Send this .onion URL to the recipient:" cat /tmp/onionurl.txt
The script launches Tor, serves the file, and prints the temporary .onion address, after which the journalist can delete the file locally without leaving a trace on a third‑party cloud.
Code Health & Issues
Low – Missing type hints – Most modules (cli/onionshare_cli/.py, desktop/onionshare/.py) lack static typing, reducing IDE support and static analysis effectiveness. Medium – Direct tor subprocess calls – onion.py invokes Tor via subprocess.Popen without robust timeout or exit‑code handling; a misbehaving Tor binary could hang the process. Low – Hard‑coded resource paths – Static files are referenced with relative paths (e.g., resources/static/css/style.css), which may break when the package is installed as a zip‑app. Low – Limited test coverage for GUI – Tests exist for the CLI (cli/tests/), but the desktop Qt interface has no automated tests. Low – No explicit license file in root – The repository contains LICENSE.txt, but the CI does not enforce license header checks. Low – CI present – GitHub Actions run lint, unit tests, and CodeQL (.github/workflows/*.yml), indicating an active CI pipeline.
Overall, the codebase compiles, has functional unit tests, and follows a clear separation between CLI, web, and GUI layers.
The Bottom Line
onionshare delivers a functional, Python‑based solution for anonymous file sharing and temporary web hosting via Tor, with both CLI and desktop interfaces. The fork is well‑structured and CI‑tested, though it would benefit from type annotations, stronger subprocess error handling, and GUI test automation. It is suitable for security‑focused teams or individuals who need a quick, self‑hosted anonymity layer without building a Tor service from scratch.