PVTKRRX

Private tracker and seedbox content inside Stremio.

Optional debrid downloader handoff. No third-party media host. Your hardware, your trackers.

What This Is

PVTKRRX is a Stremio addon system that connects your own media infrastructure to Stremio.

You bring:

• Prowlarr or another Torznab-compatible search service
• qBittorrent with WebUI enabled
• optional Real-Debrid, AllDebrid, or Premiumize credentials if you want debrid-first downloader handoff
• Stremio
• a Windows host, seedbox, VPS, or public playback endpoint depending on the route

PVTKRRX handles the bridge:

1. Stremio asks PVTKRRX for movies, TV, sports, or library rows.
2. PVTKRRX searches your configured trackers through Prowlarr.
3. If configured, PVTKRRX checks cache/debrid sources and adds debrid playback streams above the normal qBittorrent fallback.
4. PVTKRRX checks qBittorrent for already-downloaded files.
5. The selected route decides whether playback is served locally, through your home host, through public seedbox endpoints, or by redirecting to the configured debrid provider.

PVTKRRX does not host your media, does not replace your private tracker or seedbox setup, and is not itself a debrid provider.

What The Website Does

https://www.pvtkrrx.cc is the public guide, bootstrap, and hosted relay surface.

Use it for:

• reading the setup guide
• downloading or bootstrapping the app
• hosted LAN Bridge relay/token flows
• hosted Remote Seedbox token flows when your endpoints are public

Do not treat the public website as the default place to paste private localhost details. Configure private local setups on the machine that owns the runtime:

• Windows host: http://127.0.0.1:7000/configure
• self-host server: https://your-domain/configure

Route Choice

Choose the route based on where playback actually happens.

Route	Use It For	Configure It At	Playback Rule
PC Local	The Windows PC running PVTKRRX	http://127.0.0.1:7000/configure	Same-PC only. Uses the local runtime and built-in /file / /playback routes.
LAN Bridge	TV, phone, web, Apple TV, and other home devices on the same Stremio account	Windows host configure page	The hosted relay redirects back to the live Windows host while it is online at home. Away-from-home fallback needs public/linked cloud endpoints.
Remote Seedbox	Away-from-home or seedbox-first playback	Public hosted token or your own self-host server	Public hosted relay is ready-file-first. Self-hosted server mode can be playback-capable when it can read/serve the files.

Older/internal notes may still say Hybrid Home. Treat that as the current LAN Bridge home-device route unless a document explicitly says it means the old strict LAN-only profile.

How To Use It

Windows Host

Use this when your Windows PC is the playback bridge.

1. Install the current Windows release from GitHub Releases.
2. Start PVTKRRX on the Windows PC.
3. Open http://127.0.0.1:7000/configure.
4. Enter your Prowlarr and qBittorrent details.
5. Install PC Local in Stremio Desktop on that same Windows PC.
6. Use LAN Bridge for your other home devices on the same Stremio account.

For PC Local and LAN Bridge, the built-in file server can serve completed local files when the runtime can read qBittorrent's download directory. You do not need a separate third-party file server just to get started on those routes.

Self-Hosted Server (your own VPS or seedbox)

Use this when your own server or seedbox should own the runtime and keep operating without the PVTKRRX hosted relay in the request path. Everything runs on your box under your domain — no PVTKRRX-owned infrastructure stays in the path once you are set up.

You need: a Linux VPS or seedbox you control, and a domain (or subdomain) you can point at it over HTTPS.

1. Install — on your server, run:

curl -fsSL https://www.pvtkrrx.cc/install-selfhost.sh | sudo bash

The installer sets up the app, the Node runtime, production dependencies, your saved server config, an optional systemd service, and — if you pick the custom-domain option — a local Caddy reverse proxy with automatic HTTPS for your hostname. It writes PVTKRRX_PUBLIC_BASE_URL=https://<your-domain> so every manifest, poster, and playback URL uses your domain, not ours. (If you skip that and reach the server through a hostname directly, the runtime auto-detects that hostname instead — it is never hard-coded to a PVTKRRX domain.)

2. Configure — open https://<your-domain>/configure and enter your Prowlarr + qBittorrent details. Self-host mode can use private/localhost service URLs after server-admin authentication.

3. Install in Stremio — add this manifest URL (swap in your own domain):

https://<your-domain>/selfhost/manifest.json?mode=hosted

That self-host install uses its own Stremio addon id, separate from hosted Remote Seedbox token installs.

The Stremio-facing install origin needs a real public HTTPS hostname — Stremio rejects a plain http://IP:port as a stable install path (except same-PC 127.0.0.1). No domain yet? See Setup Paths If You Do Not Have A Domain below.

Setup Paths If You Do Not Have A Domain

1. Same PC: use http://127.0.0.1:7000/configure and install the PC Local route on that same machine.
2. Hosted PVTKRRX route: use the hosted LAN Bridge or Remote Seedbox token flow when you do not have your own addon URL. Remote Seedbox still needs public HTTPS playback endpoints that you control.
3. Full VPS self-host: use your own public HTTPS domain or subdomain for the addon origin. A raw http://IP:port URL is not a stable Stremio install path; a VPS setup needs DNS, a reverse proxy, and a valid TLS certificate, or you should use the hosted route instead.

Release Tags

Release numbering is app-aligned. The Windows/desktop release uses vX.Y.Z; the paired self-host/seedbox release uses vX.Y.Z-selfhost. For example, app version 1.2.0 is released as v1.2.0 and v1.2.0-selfhost.

Older v1.12.x-selfhost tags are legacy compatibility tags from the previous self-host-only counter. They are kept so pinned installer commands do not break, but new installs and updates should use the app-aligned self-host tag.

Hosted Remote Seedbox

Use this only when playback endpoints are intentionally public and reachable over HTTPS.

The hosted public relay does not proxy video bytes and does not queue-and-buffer local-only tracker playback. It is effectively a ready-file route unless you run PVTKRRX on a playback-capable self-hosted runtime.

Optional Debrid

Debrid is optional and additive. You do not need it — qBittorrent/seedbox is always a playback path, and turning debrid on never removes your qBittorrent streams. It only adds faster streams above them.

To turn it on: open /configure and paste your Real-Debrid, AllDebrid, or Premiumize key (stored encrypted in your config). That is the whole setup.

What it does:

• Cached hits show first. When the provider already holds the file, PVTKRRX adds an instant provider-backed stream above the qBittorrent/local fallback.
• Your qBittorrent streams stay. Debrid is layered on top, never a replacement — for movies, TV, and sports alike.
• Uncached sports/private-tracker handoff is hidden by default, because it usually just starts a provider download while Stremio waits on a non-playable URL. qBittorrent/seedbox stays the safe path. Re-enable it for controlled testing with PVTKRRX_DEBRID_UNCACHED_SPORTS_HANDOFF=true.

This does not make PVTKRRX a debrid service. PVTKRRX stores your provider credentials in your encrypted config, asks the provider to add/check the torrent or NZB, and redirects the client when the provider has a playable URL.

While qBittorrent or a Debrid provider is still preparing, PVTKRRX keeps the real playback request open for a longer default wait window so Stremio can receive the real /file or provider redirect from the original click when the source becomes ready. If that wait window is exhausted, the route stays retryable (425/503 plus Retry-After). For controlled Debrid testing, PVTKRRX_DEBRID_PREPARING_RESPONSE=loader makes /playback/debrid poll briefly and then serve the bundled waiting-room MP4 while the provider continues preparing. That loader is a prepare screen only; a later request is still needed once the provider is ready.

Torrentio-style native Stremio progress is a separate transport, not a Debrid handoff. When PVTKRRX_NATIVE_STREMIO_TORRENT=true is enabled, PVTKRRX may emit experimental DIRECT P2P rows using Stremio's native infoHash/fileIdx/sources contract for non-private torrent payloads. That lets Stremio download directly and show its own torrent progress UI. It is disabled by default and never emitted for torrent payloads marked private, because it bypasses qBittorrent/seedbox and announces from the Stremio device.

For setup details see docs/DEBRID_SETUP.md. For the implementation/proof worklog see docs/POSTERS_AND_DEBRID_WORKLOG_2026-05.md.

Billing And Unlocks

PVTKRRX does not currently require payment before the stream addon works.

Current behavior:

• PVTKRRX stream routes are free on the tested paths.
• Stremio account linking is used for account-aware route setup and LAN Bridge/cloud fallback, not as a payment gate.
• The self-host server password opens private server administration on your own runtime. It is not a paid service login.
• SportsMeta is a separate companion sports identity/artwork service at https://sportsmeta.pvtkrrx.cc.
• https://www.pvtkrrx.cc/sports is the public PVTKRRX-facing Sports Posters page. Its checkout buttons create SportsMeta Stripe Checkout sessions through a narrow proxy, while SportsMeta still owns member tokens, entitlement checks, and premium artwork routes.
• SportsMeta paid member routes are separate from the PVTKRRX stream addon. PVTKRRX stays free and its /sports-artwork/...png proxy consumes only public/root SportsMeta artwork; paid poster bytes and member tokens stay on the SportsMeta member addon.

Practical answer: to use PVTKRRX, configure your own Prowlarr/qBittorrent setup and install the route that matches your playback path. There is no in-app purchase step to complete first.

What Appears In Stremio

All routes expose the same addon family:

• sports discovery catalogs
• movies
• TV series
• qBittorrent library items

The route changes playback capability, not the catalog family.

Sports availability comes from your configured Prowlarr/Torznab-compatible indexers. SportsCult is one supported source/profile, not a requirement, and SportsMeta only enriches rows that already have tracker availability.

Important playback differences:

• PC Local can serve files and queue/buffer through the local runtime.
• LAN Bridge can do the same after the hosted relay redirects to the live Windows host.
• Hosted Remote Seedbox only works with public ready-file playback paths.
• Self-hosted Remote Seedbox can be playback-capable when the server can read the files and serve /file / /playback.

Local Development

npm install
# Recommended (a dev fallback secret is auto-generated if unset; required for hosted/production):
$env:ENCRYPTION_SECRET = "replace-with-a-long-local-secret"
npm start

Then open:

• configure: http://127.0.0.1:7000/configure
• root bootstrap manifest: http://127.0.0.1:7000/manifest.json
• PC Local manifest: http://127.0.0.1:7000/local/manifest.json?mode=local

Useful scripts:

npm run smoke:config
npm run smoke:guards
npm run smoke:pipeline
npm run smoke:lan-pair
npm run smoke:selfhost
npm run smoke:security
npm run smoke:desktop
npm run dist:win

See docs/TESTING.md for the current verification guide.

Hosted relay deployments should set PVTKRRX_HOSTED_RELAY=true. That keeps the public relay in guide/token mode and prevents it from serving local-only /file or /playback routes.

Repository Map

Path	Purpose
index.js	Main Express and Stremio addon server
src/handlers/	Catalog, metadata, stream, and sports artwork handlers
src/clients/	Prowlarr, qBittorrent, Cinemeta, and SportsMeta clients
src/utils/	Route, playback, storage, auth, security, and parsing helpers
public/	Public guide pages and shared configure UI
electron/	Windows desktop wrapper
scripts/	Installer, smoke checks, release, and build scripts
dist/releases/	Versioned Windows release artifacts currently tracked for published releases
docs/	Current architecture, route, status, testing, and historical notes

Documentation Canon

Read these first when checking current behavior:

• docs/CURRENT_DESIGN.md - canonical current behavior
• docs/ROUTE_FRAMEWORK.md - install route rules
• docs/STREMIO_INSTALL_TRACKER.md - verified Stremio client behavior
• ARCHITECTURE.md - component and runtime structure
• docs/PROJECT_STATUS.md - current verification state and remaining caveats

Archived or historical notes should not override those files.

Current Caveats

• Route naming drift still exists in older docs and some internal code names.
• Hosted Remote Seedbox is not proof of full cloud playback; it needs public ready-file endpoints.
• Public http://192.168.x.x:7000/... addon installs are not a stable Stremio path. Use 127.0.0.1 for same-PC PC Local, or use the hosted LAN Bridge install path for other home devices.
• Public remote/auth-protected playback still needs real-client proof before being described as fully signed off.
• The package currently references a license file that is not present in the repository. Do not invent license wording without an owner decision.