Helm - Torrent Automation Prototype

Table of Contents

• Helm - Torrent Automation Prototype
  • Table of Contents
  • Features
  • Installation
  • Why this exists
  • Roadmap
  • Changelog
  • Configuration
  • Usage
  • Disclaimer
  • Contributing
  • How it works (high-level)
  • Credits
  • License

Helm is a blazing-fast CLI-based torrent automation tool designed to fetch, filter, and send magnet links to qBittorrent.

It completely automates its own setup, orchestrating Jackett, Flaresolverr, and qBittorrent using Docker or Podman under the hood.

Features

• Automated Container Setup: No more manually configuring Jackett, qBittorrent, or Flaresolverr. setup.sh orchestrates everything via Docker/Podman compose.
• Ephemeral (One-Shot) Mode: Containers spin up when you search/download, and tear down immediately after to save RAM and CPU.
• Permanent Mode: Keep the stack running 24/7 if you prefer.
• VPN Support: Automatically route qBittorrent traffic through Gluetun (Wireguard/OpenVPN).
• Live Search & Filter: A fast, interactive CLI interface to search indexers and select torrents.
• Lite Mode (Zero Setup): Search and get Magnet links instantly using built-in Python scrapers without needing Docker or Jackett installed!
• CLI Indexer Management: Add and remove Jackett indexers directly from the command line.

Installation

Helm requires Docker (with Docker Compose) or Podman (with podman-compose) installed on your system.

Python Package (New!)

You can now install Helm directly via pip to run it natively or use the new Lite Mode:

pip install helm-torrent

Once installed, you can launch the CLI from anywhere using:

helm

Container Setup (Full Mode)

If you are on a Mac, the easiest way to get the required container engine is via Homebrew:

# To install Docker Desktop:
brew install --cask docker

# OR to install Podman Desktop:
brew install podman podman-desktop podman-compose

# Clone the repo
git clone https://github.com/Piratebird/helm.git
cd helm

# Run the automated setup script
./setup.sh

The script will guide you through:

1. Choosing your container engine (Docker vs Podman)
2. Choosing your run mode (Ephemeral vs Permanent)
3. Setting up a VPN (optional)

Why this exists

Honestly for the most part it's for myself and my own usage i wanted to get magnets of torrents and shows and it was annoying sometimes to look all over the internet for a torrent so i wanted to do that but with the terminal for the most part and heck yeah it gets the job done so far it's not perfect but it's my own so hell yeah :)

Roadmap

Helm is actively roaming the 7seas and trying to get more treasures:

• Prowlarr integration (Replacing Jackett).
• Scrumptious TUI interface.
• Better indexer management.

For more detailed tasks breakdown check TODO.md

Changelog

All notable changes are tracked in CHANGELOG.md.

Latest release: 0.9.2 — 1337x, BitTorrented and SubsPlease indexers plus EZTV now on its JSON API (the boys +153, dune +74, one piece +84 raw results), --json output no longer corrupted on fresh installs. See the full file for everything that came before.

Configuration

Helm uses a combo of env variables and config files cleanly sandboxed away from your host OS.

With the adoption of XDG standards, your configuration and state are stored natively based on your OS:

• Linux: ~/.config/helm/ (Config) and ~/.local/state/helm/ (State)
• Mac: ~/Library/Application Support/helm/ (Config and State)
• Windows: %APPDATA%\helm\ (Config) and %LOCALAPPDATA%\helm\ (State)

What these do:

• config.json: Settings only (indexers, URLs, flags) — never secrets.
• secrets.env: API keys and passwords (e.g. JACKETT_API_KEY, JACKETT_PASSWORD, QB_PASSWORD). Written with mode 0600 and resolved with env vars taking priority.
• state/.env.docker: Environment variables for the containers
• state/jackett/: Jackett configuration and indexers
• state/qbittorrent/: qBittorrent configuration and state
• Downloads/helm/: Your downloaded files

The first run migrates any legacy secrets found in older config.json files into secrets.env and rewrites the config file scrubbed.

Usage

Helm is primarily run using the included scripts to manage the Docker containers and CLI.

Typical workflow:

1. Run ./setup.sh to configure indexers, VPN, and credentials.
2. Run ./helm.sh to launch the interactive CLI and search for torrents.
3. Matching torrents are filtered and sent to qBittorrent automatically.

You can also pass arguments directly to the wrapper script:

# Force one-shot mode (spins up and tears down Docker)
./helm.sh --oneshot

# Auto-download the top result for a query
./helm.sh --oneshot --auto -q "Ubuntu 24.04" --type software

# Run built-in Lite Mode (without Jackett/Docker)
./helm.sh --lite

# Manage Jackett indexers
./helm.sh --indexers

Performance & Resource Optimization

Helm is aggressively optimized for a minimal memory footprint. While containerized applications are usually heavy, the setup.sh installer strictly throttles the Docker/Podman engines using Linux cgroups (e.g., hard-capping Jackett to 256MB).

In our Resource Benchmarks, we proved that running Helm's containerized stack actually saves RAM compared to installing the software natively!

Disclaimer

Helm does NOT host, distribute, or provide any copyrighted content.

This tool simply automates (kinda) the process of fetching RSS feeds and sending magnet links to a torrent client.

However you use this tool is your responsibility gangster.

Contributing

Contributions are welcome especially but not limited to bug fixes, refactors or documentation improvements.

If you plan to add a major feature or change behavior, it's prolly a good idea to open an issue.

with that out the way this project is real close to me since it's my official first project so let's make this bozo go (perchance).

How it works (high-level)

Helm pulls torrent RSS feeds from configured indexers, applies filtering and deduplication rules, and automatically sends matching magnet links to qBittorrent.

Credits

Shoutout to the goats! This project is built utilizing these fantastic open-source tools: qBittorrent, Jackett, and Flaresolverr.

Lite Mode Plugins: A massive thank you to the qBittorrent search engine plugins community and developers. Helm's lightweight search mode natively supports their .py plugins, making it possible to search dozens of torrent indexers instantly without any Docker overhead.

License

This project is licensed under the GPL License. See the LICENSE file for details.