Invidious

Overview

Privacy-friendly YouTube frontend on the server, accessible at inv.yhkze.net to WireGuard peers only (TLS termination via Traefik — reference Cloudflare DNS). The name resolves to 10.100.0.1, and Traefik’s wireguard-only middleware refuses any other source. Every watch page makes a YouTube request through the Mullvad relays, so a crawler alone can get them refused: Meta’s ignores robots.txt, fakes a desktop browser and loaded over a thousand watch pages a day while the instance was public. Miniflux subscribes to Invidious channel feeds so videos open here rather than on youtube.com (reference Miniflux).

Module: modules/features/invidious.nix

Two processes serve the site:

They share a 16-character key (invidious_companion_key) and talk over loopback only. Invidious reaches companion at http://127.0.0.1:8282/companion, where invidious-companion-proxy, a dedicated nginx, forwards to the serving slot.

flowchart LR
    browser[Browser] -->|HTTPS| traefik[Traefik]
    traefik -->|":3000"| inv[Invidious]
    inv --> pg[(PostgreSQL)]
    inv -->|"127.0.0.1:8282"| front[invidious-companion-proxy]
    front -->|serving| s0[Companion slot]
    front -.->|fallback| s1[Companion slots]
    s0 -->|"SOCKS5 via Mullvad"| yt[YouTube]
    s1 -->|"SOCKS5 via Mullvad"| yt

PO Tokens and YouTube Blocking

YouTube requires a proof-of-origin token to hand out video streams. Companion generates one every 30 minutes (JOBS_YOUTUBE_SESSION_FREQUENCY), staggered by 10 minutes across slots, then validates it by requesting a few real videos. Upstream refreshes every 5 minutes, but each refresh is a search plus several player requests. A token has served for over two hours here, so the longer interval costs nothing while cutting both the traffic that looks automated and the chances of three failures in a row. The refresh keeps the token current and also tests the exit address. An exit YouTube refuses fails every refresh, and once the token is gone every video page breaks while the homepage, search and subscriptions keep working.

A failed refresh leaves the previous token serving, and companion retries with a new session after 5, 15 and 60 seconds. YouTube rejects single sessions at random, so one failure says nothing about the exit address; several in a row do. A block can also show up while refreshes still succeed: Sign in to confirm you're not a bot on individual videos, or player requests answered with HTTP 500 after YouTube refuses every client with 403.

A failed refresh looks like this in the journal:

journalctl -u invidious-companion-0 -f -o cat | grep -vE 'GET /companion|POST /companion'
[INFO] Successfully generated PO token
[INFO] Validating PO token with video: <id>
[WARN] No valid format found for video <id> (<status>: <reason>), trying next video
Error: Failed to validate PO token: all validation attempts returned non-200 status codes

The Not implemented: HTMLCanvasElement.prototype.getContext error that appears alongside it is upstream-documented noise and never the cause. Reference https://github.com/iv-org/invidious-companion/issues/267.

Companion Fork

The fork lives at https://git.yhkze.net/yuuhikaze/invidious-companion and adds to upstream:

It is the invidious-companion flake input. invidious.nix vendors its Deno dependencies in a fixed-output derivation and runs src/main.ts with deno run --cached-only from pkgs.unstable.deno, since the lockfile needs Deno 2.9.

Inspect a slot’s health:

curl -s http://127.0.0.1:8283/status | jq

Deploy a new fork revision with nix flake update invidious-companion and a rebuild. When deno.lock or pkgs.unstable.deno changed, set outputHash in companionDeps to the hash the failed build reports: Deno’s vendor layout differs between releases, so a routine update that moves Deno also breaks it.

Egress

Each slot leaves either through the home line or through a Mullvad SOCKS5 proxy. The home line is the nearest exit and a residential address, which YouTube trusts more than VPN ranges; Mullvad’s address space covers the times YouTube blocks the home line, as it once did for months across both the IPv4 address and the IPv6 /64. The pool lists direct first, so one slot uses the home line whenever it is off cooldown (reference Relay Rotation).

For Mullvad, two modules cooperate:

Because the proxies are reachable through any tunnel, switching exit address is a change of proxy hostname. The tunnel is never re-keyed and no route changes.

Entry relay — every proxied request crosses the entry relay first, so its distance adds to each one. The peer is co-bog-wg-001 in Bogotá, the nearest relay at about 14 ms. Any relay accepts the same device key and address, so moving the entry means changing only the peer’s PublicKey and Endpoint.

Fetch retries — companion retries a failed YouTube fetch twice (NETWORKING_FETCH_RETRY_*), which absorbs connections a relay drops mid-request.

flowchart LR
    comp[Companion slot] -->|"SOCKS5 :1080 via 10.124.0.0/16"| wg[mullvad WireGuard link]
    wg --> entry[Entry relay co-bog-wg-001]
    entry --> proxy[Relay SOCKS5 proxy]
    proxy --> yt[YouTube]

Device key — the tunnel’s private key is the SOPS secret mullvad/private-key, and its tunnel address was assigned when the matching public key was registered with the Mullvad account. One account allows five devices, shared with the workstations (reference Mullvad).

Standby Slots

A restarted companion needs 30 to 60 seconds to generate and validate a token, and video pages fail meanwhile. Three slots therefore run at once, each through a relay in a different city, since a block tends to cover a relay’s neighbours. One slot serves; the others already hold a validated token on another exit and take over without a gap.

flowchart LR
    dog[invidious-companion-watchdog] -.->|"polls /status"| slots[Slots 0, 1, 2]
    dog -.->|"rewrites upstream.conf, reload"| front[invidious-companion-proxy]
    dog -.->|"writes n.env, restart"| slots
    front --> slots

invidious-companion-proxy reads its upstream from /run/invidious-companion/upstream.conf: the serving slot first, the others as backup. A request that a slot is down for, or answers with 403, 500 or 503, retries on the others, player POSTs included (non_idempotent).

invidious-companion-watchdog.service runs scripts/companion-watchdog.nu, which polls each slot’s /status every 10 seconds:

A slot is usable once it holds a token and shows none of these conditions. When the serving slot stops being usable, the first usable slot takes over before any restart. With no usable slot, the serving one restarts in place.

Restarting slots leaves Invidious running, since Invidious only wants the front proxy.

Relay Rotation

invidious.nix lists the egress pool nearest first: direct (the home line, an empty PROXY), then the Mullvad SOCKS5 relays in Bogotá, Miami, Atlanta, Dallas, Houston, Lima, Querétaro and the rest of South America. At boot slot 0 takes the home line and slot n the first relay of the n-th city, written to /run/invidious-companion/<n>.env. The home line is one entry like any relay: a block puts it on cooldown and its slot moves to Mullvad.

A blocked relay is recorded with its time in /run/invidious-companion/blocked.json. A slot moving on takes the nearest relay that is off its 12-hour cooldown, not held by another slot, and preferably in a city no other slot uses. Blocks expire, so if every relay is cooling down the watchdog picks the one blocked longest ago. Relays need no survey before joining the list: a blocked one costs three failed token generations, under a minute.

Show each slot’s relay, the serving order, the serving slot and what the watchdog did:

cat /run/invidious-companion/{0,1,2}.env /run/invidious-companion/upstream.conf
jq .active /run/invidious-companion/slots.json
journalctl -u invidious-companion-watchdog -o cat -n 10

Switch a slot’s relay by hand, for example to pick another country, or to the home line with an empty PROXY=. The restart is required because companion reads its environment once:

echo 'PROXY=socks5://us-atl-wg-socks5-001.relays.mullvad.net:1080' | sudo tee /run/invidious-companion/2.env
sudo systemctl restart invidious-companion-2

Confirm the tunnel itself and a relay’s exit address, independently of companion:

sudo wg show mullvad
curl --socks5-hostname co-bog-wg-socks5-001.relays.mullvad.net:1080 https://am.i.mullvad.net/json

A recent handshake in wg show means the tunnel is up. Relay hostnames follow <country>-<city>-wg-socks5-<number>.relays.mullvad.net, listed with their exact names at https://api.mullvad.net/www/relays/wireguard/ under socks_name.

Playback

default_user_preferences sets quality = "dash" with quality_dash = "auto". Upstream’s default hd720 needs the muxed itag 22 stream, which YouTube no longer serves, so it falls back to 360p. DASH serves separate audio and video streams, and the player adapts resolution to bandwidth and window size. save_player_pos = true resumes each video where it was left. The player keeps positions in the browser’s localStorage, one entry of a few bytes per video, so nothing accumulates on the server.

Preferences saved in a browser’s cookie override these defaults.

Operations

systemctl status invidious invidious-companion-{0,1,2} invidious-companion-proxy invidious-companion-watchdog
journalctl -u invidious -n 50

Verify playback end to end without a browser. A 200 and a googlevideo.com URL means tokens are valid:

curl -sL -o /dev/null -w '%{http_code} %{url_effective}\n' \
  'http://127.0.0.1:3000/latest_version?id=jNQXAC9IVRw&itag=18'

Check that the front proxy and every slot listen on loopback only, which matters because the slots share the host network namespace:

ss -tlnp | grep -E ':828[2-5]'

Restarting one slot at a time, and waiting for "ready": true in its /status, keeps a ready slot serving throughout:

systemctl restart invidious-companion-1
curl -s http://127.0.0.1:8284/status | jq .ready