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:
invidious-companion-0 to
-2 on ports 8283 to 8285 (reference Standby Slots)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
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.
The fork lives at https://git.yhkze.net/yuuhikaze/invidious-companion and adds to upstream:
GET /status, reporting whether a PO token exists, when
generation last succeeded and failed, consecutive failures, and player
outcomes over the past five minutes (bot checks and errors count;
private or age-restricted videos do not), plus the IDs of videos
answered UNPLAYABLE in that windowJOBS_YOUTUBE_SESSION_PO_TOKEN_TIMEOUT_MS, default two
minutes), since a hung generation otherwise stops all later
refreshesdeno install --frozenIt 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 | jqDeploy 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.
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:
modules/features/mullvad-proxy.nix creates a WireGuard
interface named mullvad through systemd-networkd. Its peer
allows only 10.64.0.1/32 and 10.124.0.0/16,
the ranges where Mullvad’s in-tunnel services and every relay’s SOCKS5
proxy live. Nothing else on the server enters the tunnelmodules/features/invidious.nix points each companion
slot at its own proxy,
socks5://<relay>.relays.mullvad.net:1080, set as
PROXY in the slot’s EnvironmentFile. The proxy
addresses in 10.124.0.0/16 route over the
mullvad linkBecause 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).
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:
UNPLAYABLE as if they were gone. Token refreshes and
bot-check counters stay clean, so the watchdog asks another usable slot
about each video a slot reports unplayable. Two that play elsewhere
within the five-minute window mean the relay withholds content: the slot
moves to another relay. A video unplayable everywhere, such as a country
block, changes nothingA 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.
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 10Switch 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-2Confirm 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/jsonA 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.
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.
systemctl status invidious invidious-companion-{0,1,2} invidious-companion-proxy invidious-companion-watchdog
journalctl -u invidious -n 50Verify 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