torrent-fetch

Overview

torrent-fetch is a self-hosted download management service that wraps qBittorrent-nox behind a VPN tunnel, ensuring all traffic flows through a verified encrypted connection. It provides a clean web UI and REST API with dual authentication—session-based for the web interface and named API keys for automation.

Key Features

• VPN-First Architecture: Integrates with Surfshark VPN CLI to guarantee all download traffic flows through a verified VPN tunnel before any transfers begin.
• Web Dashboard: Single-page web UI showing active downloads, queue status, and transfer statistics with real-time WebSocket updates.
• Dual Authentication: Session-based auth for browser access and named API keys for programmatic/automation use.
• State Machine Design: Downloads follow a typed state machine (queued, connecting, downloading, seeding, complete, error) with proper transitions and error recovery.
• qBittorrent Integration: Full API client wrapping qBittorrent-nox for adding, monitoring, and managing downloads.
• API-First: REST API for all operations, making it easy to integrate with other tools and automation scripts.

Technology Stack

• Backend: Python, FastAPI, uvicorn
• Real-Time: WebSocket for live progress updates
• VPN: Surfshark CLI integration with tunnel verification
• Download Engine: qBittorrent-nox API client
• Auth: Session store + JSON keystore for API keys
• Config: TOML-based configuration

Current Status

Production-ready with full VPN orchestration, download management, dual auth, and web UI operational. Comprehensive test suite and documentation.