⛵ Gorrent

Gorrent is a headless, automation-first BitTorrent daemon built in Go. It provides a robust REST API and WebSocket interface to search, score, and download torrents automatically from multiple trackers. Designed specifically for homelab environments and AI agents, Gorrent handles the heavy lifting of peer discovery, bandwidth throttling, and asynchronous file management without requiring a traditional WebUI or interactive terminal.

Origins

The original torlink by @baairon is an excellent project that deliberately focuses on being an interactive terminal application. Later, a fork of torlink by @WarlaxZ expanded upon it by adding features and wider tracker support.

Rather than trying to change their core interactive philosophy, Gorrent takes inspiration from both projects and explores a completely different direction: a headless, automation-first implementation written entirely in Go for homelab environments.

Features

Feature	Supported
REST API	✅
Docker	✅
DNS-over-HTTPS (DoH)	✅
Concurrent scraping	✅
Auto scoring	✅
RuTracker	✅
Optional CLI	✅
OpenClaw	✅
Claude Skill	✅
Hermes Skill	✅
Auto .torrent backup	✅

Fault-Tolerant Architecture

Gorrent is built from the ground up to be a headless daemon.

Flow Overview

            REST API
               │
               ▼
         Search Request
               │
               ▼
      Concurrent Scrapers
    ┌────┬────┬────┬────┐
    │YTS │1337│Nyaa│... │
    └────┴────┴────┴────┘
               │
               ▼
        Scoring Engine
               │
               ▼
       Best Torrent Found
               │
               ▼
     Download + Metadata

Reliability Features

Gorrent incorporates techniques to ensure automated environments remain resilient:

• DNS-over-HTTPS (DoH): Bypasses ISP DNS sinkholing on port 53 by routing internal DNS lookups over HTTPS (port 443) using public resolvers like Cloudflare (1.1.1.1).
• Circuit Breakers (Source Health): If a source goes down, the engine won't hang waiting for timeouts. Consecutive failures temporarily bench a source, ensuring searches remain fast.
• Dead Torrent Protection: If a torrent is added but has 0 seeders and fails to fetch metadata within 30 seconds, Gorrent automatically aborts and drops the torrent to prevent hanging the daemon.
• RuTracker Integration: Access to RuTracker's extensive catalog, unlocked by providing your session cookie in the config.

Agnostic Scoring Engine

Gorrent scores and ranks torrents based on your preferences using a data-driven Regex engine under the hood:

• Seeders Base Score: Every torrent starts with a score equal to its active seeders.
• Agnostic Term Matching: You provide a comma-separated list of terms in your config.yaml (e.g., "language": "latino, es"). Gorrent automatically compiles these into precise, word-boundary Regular Expressions. This ensures that a search for es matches the exact language code "es", but ignores the "es" inside the word "Series", without requiring you to write a regex yourself.

API

Gorrent exposes a modern REST API designed for AI agents and automation.

Auto-Download Request:

POST /api/download
Content-Type: application/json

{
    "auto": "Oppenheimer"
}

Response:

{
    "status": "started",
    "magnet": "magnet:?xt=urn:btih:..."
}

File Streaming Request: You can stream downloaded files directly using HTTP Range requests (ideal for VLC, browser, etc):

GET /files/Movie.Name.1080p/video.mkv

AI Native Integrations

Gorrent exposes interfaces specifically designed for AI agents:

• OpenClaw: The skills-for-ai/openclaw-skill/SKILL.md file and openapi.yaml endpoint allow OpenClaw agents to manage downloads natively via the API.
• Claude Desktop: The skills-for-ai/claude-skill folder provides a Custom Skill for Claude. By using Code Execution, Claude can invoke the local CLI wrapper (./gorrent.sh) to automate media fetching for you via the terminal.
• Hermes Agent: The skills-for-ai/hermes-skill/SKILL.md file provides a native skill definition tailored for Hermes Agent's CLI automation capabilities.

Deployment Guide (Docker)

The multi-arch image is built on scratch and weighs just a few megabytes.

Quick Run (Zero Config)

If you just want to run it instantly with default settings and no configuration files, use this one-liner:

docker run -d --name gorrent -p 7800:7800 -v $(pwd)/downloads:/downloads ghcr.io/x-name15/gorrent:latest

Docker Compose (Recommended)

For homelab users, mapping a config file is highly recommended.

1. Create your docker-compose.yml:

services:
  gorrent:
    image: ghcr.io/x-name15/gorrent:latest
    container_name: gorrent
    ports:
      - "7800:7800"
    volumes:
      # Map your config file and downloads folder
      - ./config.yaml:/config.yaml
      - ./downloads:/downloads
    restart: unless-stopped

2. Create your config.yaml:

daemon:
  port: 7800
  api_key: "my_super_secret_key"
  log_level: "minimal"
  data_dir: "./data"

scraper:
  dns: "cloudflare"
  rutracker_cookie: "tu_bb_session_cookie_aqui_opcional"
  sources:
    - yts
    - 1337x
    - nyaa
    - piratebay
    - fitgirl
    - subsplease
    - torrentscsv
    - rutracker
    - bittorrented
  filters:
    language: "latino, castellano, multi-subs, es"
    resolution: "1080p, 1080i"
    min_seeders: "5"

torrent:
  download_dir: "/downloads"
  auto_export_torrent: true
  max_download_rate: 5000
  max_upload_rate: 0
  auto_cleanup: true
  seed_ratio: 1.5
  max_seed_days: 3
  hardlink_dir: "/mnt/media"
  post_script: "/opt/scripts/unrar.sh"
  watch_dir: "/downloads/watch"
  delete_files_on_stop: false
  trackers:
    - "udp://tracker.opentrackr.org:1337/announce"
  category_dirs:
    movies: "/downloads/movies"
    tvshows: "/downloads/tvshows"

rss:
  interval_min: 30
  feeds:
    - url: "https://nyaa.si/?page=rss&q=subsplease+1080p"
      category: "tvshows"
      regex:
        - "Arcane"
        - "Solo Leveling"

3. Start the daemon:

docker compose up -d

Warning

Hardlink Constraints: If you use the hardlink_dir feature for Plex/Jellyfin integration, please note that hardlinks only work within the same physical disk or partition. Your download_dir and hardlink_dir MUST be on the same drive. Otherwise, the OS will reject the operation with a "Cross-device link" error.

Advanced Usage

Post-Processing Scripts (Unzipping / Moving)

If you download Repacks (like FitGirl) or Scene releases, you'll often end up with .rar or .zip files. Gorrent can automatically run a bash script when a download reaches 100%. Set the post_script field in config.yaml to the path of your script (e.g. "/opt/scripts/unrar.sh").

Gorrent will execute your script and inject the following environment variables:

• GORRENT_HASH: The InfoHash of the torrent.
• GORRENT_NAME: The original name of the torrent.
• GORRENT_PATH: The absolute path where the downloaded files live.
• GORRENT_CATEGORY: The category assigned to the torrent (e.g. movies).

We provide an example unrar.sh script in the examples/ directory of this repository!

If you don't provide a config.yaml, Gorrent will load sane defaults, but mapping it is highly recommended to tune your preferred sources and filters.

Tip: Don't want to use a specific tracker? Simply remove its name from the "sources" array in your config file.

Optional CLI

If you do want to run it manually, it ships with CLI Commands:

• Search: ./gorrent.sh search <query>
• Download by magnet: ./gorrent.sh download "magnet:?xt=urn:btih:..."
• Auto-download best result: ./gorrent.sh download --auto <query>
• Zero-config AI callback: ./gorrent.sh download --auto <query> --callback <WEBHOOK_URL> (Daemon will HTTP POST to this URL when download finishes)
• Check Status: ./gorrent.sh status
• Stop and remove a download: ./gorrent.sh stop <hash>

Releases

Releases are generated automatically from CHANGELOG.md.

License

GOrrent is licensed under the GPL v3. See LICENSE for details.

Credits

Author: Mr Jacket / Felix Manrique