mediary-scout

An agent-driven media library for your cloud drives.

Download · Website · Live Demo · 中文文档

You ask for a movie, show, or anime; an LLM agent scouts resources across your indexers, transfers the best match into your own 115 / Quark / 光鸭 drive, verifies what landed, and keeps tracking what's still missing.

Above: the read-only live demo — search → 获取 → the agent works through search, transfer, and verification.

Install

Desktop app (recommended — easiest)

1. Download and install
2. Open the app
3. Go to Settings — connect a drive, add an LLM endpoint
4. Search a title, hit 获取 — that's it

No Docker, no Postgres, no terminal. The app bundles its own SQLite data layer and runs the full engine inside an Electron shell.

Every release is machine-verified before it ships: CI installs the freshly-built Windows package on a clean runner, boots the real app, and requires an HTTP 200 health response, while the macOS build must pass native-ABI verification, signing, and notarization. Both platforms are published together in a single final step — if either gate fails, neither asset is uploaded, so a broken build can't reach the Releases page.

Docker (power users — always-on server)

cp .env.example .env   # optional — most config can be set in the UI
docker compose up -d

Then open http://:3000 and configure in Settings. Full walkthrough: docs/deploy.md.

Can't reach Docker Hub (mainland China)? See docs/deploy.md → registry mirror.

Which path?

Both paths share one codebase — all product logic is identical. The data layer (SQLite vs Postgres) is selected by the MEDIA_TRACK_SQLITE_PATH env var, not the process shell — desktop sets it automatically, Docker defaults to Postgres.

Features

Multiple drives appear as a workspace switcher with per-brand icons:

What it is

Most "media automation" either searches well but doesn't know what you're actually missing, or moves files but never verifies what landed. Mediary Scout treats acquisition as a state problem, driven by an agent that acts from evidence, not vibes:

• Multi-drive, brand-extensible — five drives today (Quark, 115, 光鸭 GuangYaPan, 123, 天翼 Tianyi), each a first-class workspace (a tree model: one account, many drives). Adding a new drive brand is a contained plugin.
• Agent-driven selection — the agent reads real search results and picks by quality preference, Chinese-subtitle needs, and de-duplication, then verifies the transfer after it happens.
• Tracking & scheduled gap-fill — season-level state machine; a scheduled sweep comes back only for shows that still have missing episodes.
• Cloud-native — it transfers shares/magnets straight into your drive (秒传 / save), it does not download to a local disk.

Supported drives

Five Chinese cloud drives, each a first-class workspace — ordered by how many PanSou resources each can consume (115 and 123 are dual-path: own share links and magnets):

• Quark / 夸克 (quark) — share-link transfer (no magnet web API). The largest share pool on PanSou by far.
• 123网盘 (pan123) — dual-path like 115: share-link transfer (123pan.com/s/…) and magnets via its native offline-download API (resolve → submit → poll). A magnet is a magnet — whether it came from PanSou or a Prowlarr indexer. QR login (~90-day token) or paste a token. Free accounts can transfer (server-side copy costs no download quota). Setup guide
• 115 (pan115) — full support: 115 share links and magnets (built-in offline path, plus Prowlarr).
• GuangYaPan / 光鸭云盘 (guangya) — Xunlei-family drive; magnet / offline-download only (transfers magnet/ed2k/BT via its offline-task API — it does not transfer share links in v1). Token auth. Pairs well with Prowlarr. Setup guide
• Tianyi / 天翼云盘 (tianyi) — share-link transfer (cloud.189.cn/t/…); QR login or paste an SSON cookie. Smallest share pool on PanSou today (weak for movies, workable for shows/anime). Setup guide

Measured share volume per drive (2026-07 point-in-time sample: six popular titles across movie / drama / anime, one PanSou instance with curated channels — your channels will vary):

New brands plug into a storage-brand registry; the bulk of adding one is a drive client + a storage executor for that drive's transfer API.

Agent API (agent-first control)

Both the desktop app and the container expose a local HTTP API that lets any coding agent (Claude Code, Codex, opencode, …) operate Mediary Scout without opening the GUI — change settings, trigger acquisitions, check download progress.

Desktop: automatic — on first launch the app writes a discovery file to ~/.mediary/agent.json. Container: set MEDIA_TRACK_AGENT_TOKEN env var to opt in.

Install the agent skill:

mkdir -p ~/.claude/skills/ && cp -r skills/mediary-scout ~/.claude/skills/      # or ~/.codex/skills/, ~/.config/opencode/skills/

Then tell your agent things like "帮我找进击的巨人第二季" or "蜘蛛侠下好了吗" or "把画质改成 high". See skills/mediary-scout/SKILL.md for the full trigger list.

All require Authorization: Bearer . No token configured → 404 (invisible). Wrong/missing token → 401.

Architecture

A web app enqueues work; a long-running worker drives a sandboxed agent that has narrow, audited powers while the deterministic workflow owns every side effect and re-reads real state to verify.

flowchart LR
    UI["Web UI
(Next.js)"] -->|enqueue| Q["Postgres / SQLite
+ run state"]
    Q --> W["In-process worker"]
    W --> AG["V2 sandbox agent"]
    AG -->|search| SRC["PanSou / Prowlarr"]
    AG -->|transfer| DR["Quark / 115 / 光鸭 / 123 / 天翼 drive"]
    AG -->|read back| DR
    AG -->|verify + mark| Q
    Q -->|realtime| UI
    CRON["Scheduled sweep"] -->|gaps only| Q

• State lives in Postgres (container) or SQLite (desktop) — runs are resumable across restarts (the agent rebuilds from real drive + DB state, not cached chat history).
• Metadata comes from TMDB (with a built-in proxy fallback so it works out of the box); resource search from PanSou and optionally Prowlarr (torrent/magnet indexers).

Demo

** Try it live: demo.mediaryscout.app**

A public, read-only demo — mock drives, real TMDB search across the whole catalog, and a scripted acquisition you can watch land in the library. No drive connect, no transfers, nothing persists.

Deploy (Docker)

Self-host on a NAS, a router (软路由), a spare PC, or a VPS — and reach it from your phone / TV via Tailscale or a Cloudflare Tunnel (no public IP needed; never expose :3000 raw). Full walkthrough: docs/deploy.md.

Deploy with an agent

Prefer to have an AI agent walk you through it? Paste this prompt:

…

`

Disclaimer. Mediary Scout is open-source, self-hosted software. It is not offered, and never will be offered, as a hosted service — you run your own instance and bring your own drive / LLM / metadata credentials. It performs the same kinds of file operations you could do by hand in your own cloud drive. See docs/distribution-and-legal-positioning.md for the project's stance.

Status & limitations

• Self-hosted, for advanced users; you need usable access to a supported drive (Quark/115/光鸭/123/天翼 — a membership is most practical on 115/夸克; 123/天翼 work on free accounts).
• Scheduled monitoring is most valuable on an always-on host (Docker path).
• This is not a hosted product and ships no hosted backend.

Credits & upstream

Built on top of, and grateful to:

• PanSou — resource search backend
• Prowlarr — indexer manager (optional)
• p115client — 115 API reference
• AList — GuangYaPan (光鸭云盘) API integration reference (the drivers/guangyapan driver)
• p123client — 123网盘 API reference
• cloud189-auto-save / cloudpan189-api — 天翼云盘 API references
• TMDB — metadata (this product is not endorsed or certified by TMDB)

Not affiliated with 115, Quark, 光鸭云盘 (GuangYaPan), 123网盘, 天翼云盘, TMDB, or any indexer. Mediary Scout is an independent, disciplined workflow built around these pieces.

Community

This project actively participates in and endorses the LINUX DO community — a Chinese-language technical community where many of this project's users self-host, and where deployment questions get answered fast.

Star History