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](https://demo.mediaryscout.app) โ search โ ่ทๅ โ the agent works through search, transfer, and verification.*
## Install
### Desktop app (recommended โ easiest)
| Platform | Download | Notes |
|---|---|---|
| **macOS** (Apple Silicon) | [DMG โ Releases](https://github.com/fancydirty/mediary-scout/releases/latest) | Signed + notarized, no Gatekeeper warning |
| **Windows** (x64) | [EXE installer โ Releases](https://github.com/fancydirty/mediary-scout/releases/latest) | Unsigned โ SmartScreen will prompt, click "run anyway" |
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)
```bash
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](docs/deploy.md)**.
> ๐จ๐ณ **Can't reach Docker Hub (mainland China)?** See **[docs/deploy.md โ registry mirror](docs/deploy.md#ๅฝๅ
ๆๅปบๅ ้่ฟไธไธ-docker-hub)**.
### Which path?
| | Desktop App | Docker |
|---|---|---|
| **Best for** | Personal use, Mac/Windows | NAS, server, 24/7 monitoring |
| **Setup** | Download + open | `docker compose up -d` |
| **Database** | SQLite (default) | Postgres (default; SQLite via `MEDIA_TRACK_SQLITE_PATH`) |
| **Agent API** | โ
| โ
|
| **Always-on patrol** | โ (runs when app is open) | โ
|
| **Multi-user** | โ | โ
|
| **Remote access** | Local only | Tailscale / Cloudflare Tunnel |
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
| | |
|---|---|
| **Search โ acquire** โ find a title, hit ่ทๅ, the agent takes over |  |
| **Library wall** โ what you have, per drive, with missing / airing badges |  |
| **Show detail** โ season coverage, gaps, tracking state |  |
| **Realtime activity** โ a live queue + agent action ticker while it works |  |
| **Notifications** โ per-acquisition + daily digest, multi-channel push |  |
| **Settings** โ drives, quality, language, LLM (BYO-key), Prowlarr, PanSou |  |
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** โ 115, Quark, and ๅ
้ธญ (GuangYaPan) today, 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
Three Chinese cloud drives, each a first-class workspace:
- **115** (`pan115`) โ full support, including magnet via Prowlarr.
- **Quark** (`quark`) โ share-link transfer (no magnet web API).
- **GuangYaPan / ๅ
้ธญไบ็** (`guangya`) โ Xunlei-family drive; **magnet / offline-download first** (transfers magnet/ed2k/BT via its offline-task API, like 115's offline path โ it does **not** transfer 115/Quark/ๅ
้ธญ share-links in v1). Token auth (`access_token` + `refresh_token`). Pairs well with Prowlarr. **[Setup guide](docs/deploy.md#ๅ
้ธญไบ็guangyapan่ฟๆฅ)**
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:
```bash
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`](skills/mediary-scout/SKILL.md) for the full trigger list.
| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/agent/config` | Read settings (secrets masked) |
| `PUT` | `/api/agent/config` | Partial update (rejects masked `***` writes) |
| `POST` | `/api/agent/acquire` | Search TMDB โ queue (409 on ambiguity) |
| `POST` | `/api/agent/patrol` | Trigger a patrol sweep |
| `GET` | `/api/agent/library` | Tracked titles + missing episodes |
| `GET` | `/api/agent/activity` | Active queue + recent notifications |
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.
```mermaid
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["115 / Quark / ๅ
้ธญ 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](https://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](docs/deploy.md)**.
### Deploy with an agent
Prefer to have an AI agent walk you through it? Paste this prompt:
````markdown
You are deploying Mediary Scout, a self-hosted media-acquisition agent. Follow the repo's docs/deploy.md. Ask the user the questions below IN ORDER, then execute.
## MUST ask (don't start without answers)
1. **Where are you deploying?** Which machine (NAS / router / spare PC / VPS), and how do I operate it โ SSH in, or run commands on its local terminal?
2. **Single-user or multi-user?** Default single-user (just you). Multi-user lets family/friends each register, bind their own drives, and keep separate libraries.
## SHOULD ask (have defaults, but confirm preference)
3. **Local-only, or reach it from outside?**
- Local network only (default โ open `http://:3000` from devices on the same LAN)
- Tailscale (private mesh โ recommended for home; no public IP, auto-encrypted)
- Cloudflare Tunnel (public HTTPS like `https://media.yourdomain.com` โ needs a domain on Cloudflare + Access in front)
4. **Configure real acquisition now, or just get it running first?** Real acquisition needs a 115/Quark/ๅ
้ธญ drive + an LLM endpoint (OpenAI-compatible) + (if using 115) 115 directory CIDs. Skipping means it boots and you can look around, configure later in Settings.
## OPTIONAL โ one question, skip all if the user doesn't care
5. Any of these you want to set up now? Reply "none" to skip and use defaults:
- Push notifications (Bark / Server้
ฑ / WeChat Work / webhook)
- Your own TMDB key (default: works out of the box via the author's proxy)
- Prowlarr magnet aggregation (115 only)
- Build acceleration (registry mirror + npm mirror โ needed in mainland China)
## Then execute
- `git clone https://github.com/fancydirty/mediary-scout && cd mediary-scout`
- If build acceleration (mainland China): `docker compose build --build-arg NPM_REGISTRY=https://registry.npmmirror.com` + a registry mirror in `/etc/docker/daemon.json`, **before** the first `up`
- `docker compose up -d` (first build takes a few minutes)
- If multi-user: add `MEDIA_TRACK_MULTI_USER=1` to `.env`, then `docker compose up -d web`
- If Cloudflare Tunnel: follow docs/deploy.md ยง"ๆนๅผไบ" โ create the tunnel in the Zero Trust dashboard, put the token in `.env` as `TUNNEL_TOKEN=`, `docker compose --profile tunnel up -d`, and **add Cloudflare Access** (never expose the instance without auth)
- Open `http://:3000`, walk the user through Settings (drive / LLM / optional extras)
- Verify it's up, report the URL, and tell them how to upgrade (`git pull && docker compose up -d --build`)
````
> **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](docs/distribution-and-legal-positioning.md) for the project's stance.
## Status & limitations
- Self-hosted, for advanced users; you need usable 115/Quark/ๅ
้ธญ access (a membership is most practical).
- 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](https://github.com/fish2018/pansou-web) โ resource search backend
- [Prowlarr](https://github.com/Prowlarr/Prowlarr) โ indexer manager (optional)
- [p115client](https://github.com/ChenyangGao/p115client) โ 115 API reference
- [AList](https://github.com/AlistGo/alist) โ GuangYaPan (ๅ
้ธญไบ็) API integration reference (the `drivers/guangyapan` driver)
- [TMDB](https://www.themoviedb.org/) โ metadata (this product is not endorsed or certified by TMDB)
Not affiliated with 115, Quark, ๅ
้ธญไบ็ (GuangYaPan), TMDB, or any indexer. Mediary Scout is an independent, disciplined workflow built around these pieces.
## Star History
