InnerTube Proxy

YouTube's InnerTube player and updated_metadata endpoints return LOGIN_REQUIRED from certain datacenter IPs. The InnerTube Proxy is a standalone Rust binary (Actix Web) that forwards these requests from a host with a trusted IP.

Architecture

API Server (Hetzner) ── POST ──▶ Rust Proxy (Proxmox) ── POST ──▶ YouTube InnerTube
                                 innertube-proxy                    /youtubei/v1/*
                     ◀── Response ───────────────────── ◀── Response ──────────────

Only player (total views) and updated_metadata (like count) are proxied. Chat polling (get_live_chat) and broadcast discovery (browse) call YouTube directly — they work from datacenter IPs and are latency-sensitive.

Configuration

Setting	ENV Override	Default	Description
innertube_proxy_url	LUMIO__YOUTUBE__INNERTUBE_PROXY_URL	unset	Proxy base URL. Unset = call YouTube directly.
innertube_proxy_token	LUMIO__YOUTUBE__INNERTUBE_PROXY_TOKEN	unset	Bearer token for proxy auth.

When both are set, the YouTube worker routes player and updated_metadata requests through the proxy. When unset (local dev), requests go directly to YouTube.

Proxy Routes

Route	YouTube Target
POST /player	youtubei/v1/player
POST /updated-metadata	youtubei/v1/updated_metadata
GET /health	Returns 200 (Docker healthcheck)

The api_key query parameter is forwarded from the incoming request.

Auth

The proxy validates Authorization: Bearer \{token\} against the INNERTUBE_PROXY_TOKEN env var. Invalid or missing tokens return 401.

Deployment

The proxy runs as an OCI container built with Bazel:

# Build image
bazel build //apps/innertube-proxy:innertube-proxy_image

# Push to registry
bazel run //apps/innertube-proxy:innertube-proxy_push

Docker Compose:

innertube-proxy:
  image: ghcr.io/zaflun/lumio/innertube-proxy:latest
  environment:
    INNERTUBE_PROXY_TOKEN: "${INNERTUBE_PROXY_TOKEN}"
    LISTEN_ADDR: "0.0.0.0:3100"
    RUST_LOG: "info"
  ports:
    - "3100:3100"
  restart: unless-stopped
  healthcheck:
    test: ["CMD", "wget", "-q", "--spider", "http://localhost:3100/health"]
    interval: 30s
    timeout: 5s
    retries: 3

The API connects via Docker network: LUMIO__YOUTUBE__INNERTUBE_PROXY_URL=http://innertube-proxy:3100

Token Management

Generate a token:

openssl rand -base64 32

Set it as env var on the proxy container (INNERTUBE_PROXY_TOKEN) and the API server (LUMIO__YOUTUBE__INNERTUBE_PROXY_TOKEN). Both must match.

Health Check

The InnerTube health check workflow uses the proxy (via INNERTUBE_PROXY_URL and INNERTUBE_PROXY_TOKEN GitHub secrets) to verify total_views end-to-end. If the proxy is down, the health check emits a warning or failure alert to Discord.

Key Files

File	Purpose
apps/innertube-proxy/src/main.rs	Actix Web proxy server
apps/innertube-proxy/BUILD.bazel	Bazel build + OCI image targets
crates/lo-youtube-api/src/innertube/browse.rs	InnerTubeProxy struct, proxy routing
apps/api/src/config.rs	YouTubeSettings proxy fields
apps/api/src/workers/youtube.rs	Proxy config wiring