# Gorrent

> Search and download torrents natively using the local Gorrent daemon.

- Skill: `x-name15/gorrent` (Agent Skill)
- Install (CLI): `npx skillmds@latest add x-name15/gorrent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-name15/gorrent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: x-name15 (https://skillmd.com/u/x-name15)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/x-name15/gorrent

---


# Gorrent Skill

You are interacting with Gorrent, a headless torrent search and automation daemon running at `http://localhost:7800`.
If the user has enabled API Key security, you MUST include the `X-API-Key` header in all HTTP requests (or pass `?apikey=<key>` as a query param).

When the user asks you to search for torrents or download something, use your HTTP tools to communicate with the Gorrent REST API.

## Endpoints

### 1. Search Torrents
`GET /api/search?q=<query>[&source=<name>]`

Returns a JSON array of results. Pick the one with the highest `score` or `seeders`.

**Available `source` values:** `yts`, `nyaa`, `piratebay`, `1337x`, `eztv`, `subsplease`, `fitgirl`, `torrentscsv`, `rutracker`, `bittorrented`

### 2. Download Torrent
`POST /api/download`

```json
{
  "magnet": "magnet:?xt=urn:btih:... (or bare 40-char hash)",
  "auto": "search query (Gorrent auto-picks best result)",
  "category": "movies | tvshows | anime | ...",
  "source": "restrict auto-search to one scraper",
  "callback": "https://your-webhook-url (POST when 100% done)"
}
```
Use `magnet` OR `auto`, not both. `category`, `source`, and `callback` are all optional.

**Webhook payload** (sent to `callback` when complete):
```json
{"event": "completed", "name": "...", "hash": "..."}
```

### 3. Status
`GET /api/status`

Returns array of active torrents:
```json
[{"hash":"...", "name":"...", "downloaded":102400, "length":1073741824, "peers":12}]
```

### 4. Stop Torrent
`DELETE /api/torrent?hash=<40-char-hash>`

Drops the torrent from the engine. **Files remain on disk** — safe for Plex/Jellyfin.

### 5. WebSocket (Real-Time)
`ws://localhost:7800/api/ws` — streams the full status array every 1 second.

### 6. Prometheus Metrics (No Auth)
`GET /metrics` — exports:
- `gorrent_torrents_active`
- `gorrent_bytes_downloaded`
- `gorrent_bytes_uploaded`

### 7. Health Check (No Auth)
`GET /health` → `{"status": "ok"}`

### 8. OpenAPI Spec (No Auth)
`GET /api/docs` → returns the full OpenAPI YAML specification.

### 9. File Streaming
`GET /files/<relative/path>` — serves the entire `download_dir` over HTTP with `Range` header support.
Requires authentication if `api_key` is set. Ideal for streaming video directly in a browser, VLC, Plex, or Jellyfin.
Example: `GET /files/Movie.Name/video.mkv`

### 10. Seed Local Path
`POST /api/seed`
```json
{
  "path": "/absolute/path/to/folder/or/file",
  "category": "movies | tvshows | music | ..."
}
```
Turns an existing local folder or file into an active torrent and starts seeding it immediately without re-downloading. Saves the `.torrent` file in `download_dir` and returns its magnet URI.

## Config Automation (Zero-Touch UX)
If the user asks you to configure anything, directly modify `config.yaml`. Full schema:

### `daemon` block
- `port` (int): Daemon port. Default `7800`.
- `log_level` (string): Verbosity level. Options: `minimal` (default) or `debug`.
- `api_key` (string): Shared secret for auth.
- `data_dir` (string): State files directory. Default `"./data"`.

### `scraper` block
- `sources` (array): Active scrapers. Valid: `yts`, `nyaa`, `piratebay`, `1337x`, `eztv`, `subsplease`, `fitgirl`, `torrentscsv`, `rutracker`, `bittorrented`.
- `filters` (map): e.g. `language: spanish` and `quality: 1080p`.
- `dns` (string): DNS-over-HTTPS resolver. e.g. `"cloudflare"`, `"google"`, or raw IP.
- `rutracker_cookie` (string): RuTracker `bb_session` cookie.

### `torrent` block
- `download_dir` (string): Root download directory.
- `auto_export_torrent` (bool): Auto-save `.torrent` file alongside each download.
- `trackers` (array): Extra UDP/HTTP trackers appended to every magnet link.
- `category_dirs` (map): Category → absolute path mapping. e.g. `movies: /downloads/movies`.
- `max_download_rate` (int, KB/s): Download cap. `0` = unlimited.
- `max_upload_rate` (int, KB/s): Upload/seed cap. `0` = unlimited.
- `auto_cleanup` (bool): Default `false`. Enables Garbage Collector.
- `seed_ratio` (float): GC drops torrent when ratio reaches this (e.g. `1.5`).
- `max_seed_days` (int): GC drops torrent after seeding this many days.
- `hardlink_dir` (string): **Optional.** Directory for Plex/Jellyfin hardlinks. Must be on the same physical disk as `download_dir` or it will fail.
- `post_script` (string): **Optional.** Bash script path run on completion. Env vars: `GORRENT_HASH`, `GORRENT_NAME`, `GORRENT_PATH`, `GORRENT_CATEGORY`.
- `watch_dir` (string): **Optional.** Drop `.magnet` or `.txt` files (containing a magnet URI) here → Gorrent auto-downloads them within 5 seconds and moves them to `watch_dir/handled/`. Leave empty (default) to disable.
- `delete_files_on_stop` (bool): **Optional, default `false`.** When `auto_cleanup` GC drops a torrent, also permanently deletes its files from disk. **Default is `false`** — Gorrent always keeps files on disk for Plex/Jellyfin. Only set to `true` if the user explicitly asks for disk space rotation.

### `rss` block
- `interval_min` (int): Polling interval in minutes.
- `feeds` (array):
  - `url` (string): RSS feed URL.
  - `category` (string): Target category for downloads.
  - `regex` (array of strings): Case-insensitive title patterns. Empty = download all.

Always return status/results nicely formatted to the user.

## Resilience & State
Gorrent features a **Self-Healing Boot** architecture.
- **State Persistence**: Active torrents are automatically saved to state.json inside the download_dir. If Gorrent restarts, it silently reloads all torrents in the background, pausing or resuming them instantly. Do not attempt to manually re-add torrents upon boot.
- **Crash Logging**: Fatal engine panics are trapped and saved to crash-logs/crash.log in the working directory without terminating the daemon.