Providers
How Kunai chooses providers, retries, recovers, and falls back — without scraper internals.
Kunai resolves playable streams through direct HTTP provider adapters. You pick a title; Kunai asks registered providers for stream inventory; playback goes to mpv.
This page explains user-visible provider behavior. It does not document scraper internals, crypto constants, or site-specific extraction logic.
Third-party providers
/recover, then /fallback, then /diagnostics - each command maps to a distinct recovery strategy.Active providers
Live registry synced from the CLI when docs are generated. Click a provider name to jump to its notes below.
| Provider | Domain | Media | Status | Description |
|---|---|---|---|---|
| Videasyrecommended videasy | videasy.to | movie, series | Active | Fast direct streams with source selection and subtitles |
| VidLinkrecommended vidlink | vidlink.pro | movie, series | Active | Movies and series with multi-language subtitles |
| Rivestreamrecommended rivestream | rivestream.app | movie, series | Candidate | Beta movies/series source — recommended default, quality can vary by title |
| AniDBrecommended anidb | anidb.app | anime | Active | Anime streams via anidb.app — ani-cli v5 primary source |
| AllManga allanime | allmanga.to | anime | Active | Anime episodes in sub and dub — the primary anime source |
| Miruro miruro | www.miruro.bz | anime | Candidate | Alternate anime source — useful when a title is missing elsewhere |
| YouTuberecommended youtube | youtube.com | video | Production | YouTube via Invidious search and yt-dlp playback |
Mode defaults at a glance:
- Movies / series — Videasy, VidLink, Rivestream (candidate)
- Anime — AniDB (
anidbid, default), AllManga-compatible client (allanimeid, fallback), Miruro (manually selectable) - YouTube — dedicated video mode via Invidious search + yt-dlp playback
Legacy id vidking maps to Videasy in config and cache. Cineby is research-only — not registered for production resolve.
Videasy
When to use: default movies and series path. Fast direct streams with source selection and subtitles.
Config id: videasy (legacy alias vidking still accepted). Prefer this as provider unless a title works better elsewhere.
Caveats: catalog and source availability can change; use /recover then /fallback when a stream dies.
VidLink
When to use: movies and series with multi-language subtitle inventory.
Config id: vidlink. A solid second default in providerPriority after Videasy.
Caveats: subtitle language coverage is not guaranteed for every title.
Rivestream
When to use: movies and series when you want another recommended default in the chain. Marked candidate — quality varies by title.
Config id: rivestream. Safe to keep in priority after Videasy/VidLink.
Caveats: treat failures as normal for a beta candidate; fallback is expected.
AniDB
When to use: the default anime route (sub and dub). Kunai searches AniDB directly, routes each season to its own AniDB title, and resolves streams from that title.
Config id: anidb for animeProvider / animeProviderPriority.
{
"animeProvider": "anidb",
"animeProviderPriority": ["anidb", "allanime"]
}Caveats: anime mode must be active (-a or anime mode in the shell). Some networks need curl
installed for AniDB requests to get past Cloudflare. If a season cannot be matched unambiguously,
Kunai reports that rather than playing a different season.
AllManga
When to use: fallback anime source (sub and dub) when the AniDB route does not resolve. Display name is AllManga; the runtime id is allanime.
Config id: allanime for animeProvider / animeProviderPriority. To make it the primary anime
source instead of the fallback:
{
"animeProvider": "allanime",
"animeProviderPriority": ["allanime", "anidb"]
}Caveats: anime mode must be active (-a or anime mode in the shell). Do not confuse the display name with the config id.
Miruro
When to use: alternate anime source when a title is missing or weak on AllManga.
Config id: miruro. Candidate status — keep after allanime in priority.
Caveats: quality and catalog coverage vary; use as fallback, not as the only anime provider.
YouTube
When to use: YouTube mode for video search and playback (Invidious search, yt-dlp stream handoff to mpv).
Config id: youtube. Switch with /youtube-mode or the mode cycle.
Caveats: requires network; yt-dlp must be available for resolve. This is not a TMDB movie/series provider. Kunai does not bypass DRM or circumvent YouTube access controls — it only forwards optional cookies you already have to yt-dlp/mpv.
Cookie safety (age-restricted / members)
Optional keys under youtubeMetadata in ~/.config/kunai/config.json (also editable from /settings → YouTube):
| Key | Safe usage |
|---|---|
cookiesFromBrowser | Browser name for yt-dlp --cookies-from-browser (for example chrome, firefox). Reads cookies from that browser profile on your machine. |
cookiesFile | Absolute path to a Netscape cookie file passed as yt-dlp --cookies. Relative paths are easy to mis-resolve — use an absolute path. |
Safety rules:
- Never paste cookie file contents into issues, chats, or support bundles.
- Prefer
cookiesFromBrowserwhen it works; keepcookiesFileprivate on disk. - Before sharing
/export-diagnosticsor/report-issueoutput, open the redacted bundle locally and confirm cookies/tokens/paths stay redacted. - There is no shipped default cookie file and no claim of DRM bypass.
How resolution works (user view)
You select a title and episode
Kunai builds a resolve request from your mode, language profiles, and any per-title provider preference.
Kunai tries the default provider first
Your provider or animeProvider config key sets the session default. Startup priority policy may influence first pick.
Falling back to another provider can change the available source inventory (quality ladder, sub/dub mix). Title and catalog identity never silently cross to another catalog: an advanced search with no compatible catalog is reported as unsupported rather than quietly answered by TMDB.
Provider-local cycling
Within one provider, Kunai may try multiple sources, servers, or variants before giving up. Diagnostics shows this as retry progress — not necessarily an error.
Global fallback
If the active provider is exhausted, skipped, or unhealthy for this request, Kunai moves to the next id in your priority list.
Stream handoff
The winning stream becomes mpv input with required headers and subtitle attachments. Inventory is cached for faster re-selection.
More detail on pickers: Media selection.
Fallback chain configuration
Configure order in /settings or ~/.config/kunai/config.json:
{
"provider": "videasy",
"providerPriority": ["videasy", "vidlink", "rivestream"],
"animeProvider": "anidb",
"animeProviderPriority": ["anidb", "allanime"]
}The anime client shows as AllManga in the UI; the config id remains allanime.
Rules:
- Empty priority arrays use registry default order.
- Unknown ids in the list are ignored.
- Providers not listed remain available after configured entries.
- Per-title overrides in
titleProviderPreferenceswin over history provider on resume.
See Customization.
Retry vs recover vs fallback
Kunai uses three distinct user-facing actions. They are not interchangeable.
| Action | Keys / command | What happens |
|---|---|---|
| Recover | r, /recover | Refresh current playback intent on the active provider — new resolve, cache revalidation, or mpv reload |
| Retry (automatic) | — | Provider-local cycling through sources/variants before global fallback; shown in diagnostics timeline |
| Fallback provider | f, /fallback | Stop active provider; global engine picks next compatible provider |
| Recompute | /recompute | Bypass stream cache and provider health memory for current episode |
Recover before fallback
When a stream dies mid-playback, try recover first. Fallback switches providers and may change source quality or subtitles.
Recovery mode setting
recoveryMode in config changes default aggressiveness:
| Mode | Behavior |
|---|---|
guided (default) | Explain failures; suggest recover then fallback |
fallback-first | Prefer moving to next provider sooner after classified failures |
manual | Minimal automatic fallback; user drives /recover and /fallback |
Provider health and cache
Kunai remembers provider health locally to avoid hammering known-bad paths. Health updates come from resolve outcomes — not from your home network being offline.
- Cache hit — reuse recent stream inventory when still valid.
- Stale cache — revalidate before play when health checks fail.
- Cold resolve — full provider lookup when no usable cache exists.
/diagnostics shows cache provenance and health deltas without exposing signed URLs.
Network-unavailable failures stop cycling early. Kunai does not mark unrelated providers as unhealthy because your Wi-Fi dropped.
Domain overrides
Advanced users can point providers at alternate base domains via ~/.config/kunai/providers.json:
{
"videasy": "https://mirror.example"
}Overrides affect URL construction only. They do not register new providers or bypass site authentication.
Provider geo relay
Some provider metadata APIs are geo-blocked from some countries while the final video CDN still works globally. Kunai supports an optional user-owned provider relay for those metadata calls.
What it does:
- Routes provider API/search/source JSON through your relay when
providerRelay.baseUrlis set. - Keeps playback direct: mpv receives the final stream URL and fetches it from your network.
- Uses provider manifest allowlists, so it is not an arbitrary URL proxy.
What it does not do:
- Kunai does not operate a public relay for you.
- Kunai does not proxy or host video by default.
- The relay does not bypass provider login or DRM.
Local contributor smoke:
bun run dev:relay
KUNAI_RELAY_BASE_URL=http://127.0.0.1:8787 bun run test:live:relay-allanimeDeploy/config details live in apps/relay-server/README.md for source
checkouts.
When providers fail (expected behavior)
Provider catalogs drift. Failure is operational, not exceptional.
- Diagnostics records failure class and stage.
- Kunai attempts provider-local retries when inventory exists.
- Global fallback runs when configured and appropriate.
- You stay in the shell with context intact — search, history, and offline library remain available.
If all providers fail, Kunai explains why in diagnostics and the shell footer. Collect evidence with /export-diagnostics — see Troubleshooting.
What Kunai does not do with providers
- No browser/Playwright scraping in the active beta runtime
- No Kunai-hosted proxy or stream relay; the optional provider geo relay is user-owned and metadata-only by default
- No guarantee of subtitle language, quality tier, or dub availability
- No silent provider switching without user action (except configured automatic fallback within policy)
See Supported and unsupported.
Picking a provider manually
Before playback starts:
- Provider picker in the starting-episode flow when multiple providers are compatible.
/sourceor/tracksduring playback when inventory supports switching without full re-resolve.
After explicit pick, Kunai stores per-title preference for future resume.
Related
- Playback and recovery — resume, replay, hotkeys
- Troubleshooting — provider resolve failed
- Customization — priority lists and overrides
- Diagnostics and reporting — attempt timelines
Last updated on