Invidious: interface, media paths and operational responsibility
Invidious architecture: web requests, account state and media bytes follow different paths
Trace the Crystal/Kemal frontend, PostgreSQL initialization and companion routing without assuming that every request traverses one proxy.
What you will learn
- Read startup as dependency wiring
- Companion routing has a simple and an advanced shape
- Separate control metadata, account state and streamed bodies
Before you start
- Basic HTTP and container concepts
- Ability to distinguish application state from media traffic
Explain the dependency and trust boundaries, prepare a verifiable trial and interpret source/model evidence without overclaiming.
Key takeaways
- Startup, persistent state and media delivery are separate architectural concerns.
- public_url changes how browsers reach companion.
- Cached companion selection is not a general failover or load-balancing guarantee.
Read startup as dependency wiring
The application entry point loads Kemal, configuration, database modules, routes, background jobs and upstream helpers. It opens PostgreSQL from the configured database URL and exits on a connection failure. That makes persistent state a startup dependency in the inspected path, not an optional browser-only feature that can be ignored when the page looks static.
The same entry point constructs pools for YouTube, image requests and companion communication. These are different responsibilities even when they live in one process. A page request may involve metadata and application state, while the bytes delivered by a player can involve another route. Diagramming every arrow as the same generic API call hides the operational boundaries.
Companion routing has a simple and an advanced shape
The configuration reference describes private_url as the internal application-to-companion address. With no public_url, the application proxies companion requests. When public_url is configured, user requests can reach companion directly through separately configured reverse-proxy routes. The word private describes the intended topology; operators must still enforce network isolation and key handling.
For multiple configured companions, the reference says a companion is randomly chosen when video data is retrieved and retained in that metadata cache entry. A new choice occurs after the cached metadata expires. This is not evidence of per-packet balancing, transparent failover or deterministic load distribution. Capacity planning must consider the cache behavior and the selected deployment topology.
Separate control metadata, account state and streamed bodies
The inspected companion route forwards GET, POST and OPTIONS through the companion pool, copies the response status and headers, and streams the body using IO.copy. That is a useful code-level distinction from buffering an entire video in a string. It does not, by itself, establish memory bounds across every layer or prove that every error becomes a useful client response.
Account history and subscriptions live in instance state, and background work has its own lifecycle. Diagnose failures by boundary: database connection, web route, companion communication, upstream response and browser playback. A working search page can coexist with a failing media path. The diagrams here illustrate inspected contracts; no distributed trace or live topology measurement was collected.
Implementation steps
- 1
Trace configuration loading and PostgreSQL initialization.
- 2
Map metadata, account-state and media-body requests separately.
- 3
Record private_url and any public_url reverse-proxy routes.
- 4
Assign a health check and owner to each boundary.
Copy-ready example
{
"privateUrl": "application-to-companion",
"publicUrlConfigured": "browser-to-companion route requires edge configuration",
"selection": "retained with cached video metadata",
"liveTraceCollected": false
}Frequently asked questions
Does public_url mean the database should be public too?
No. It concerns a browser-facing companion route. Database exposure is a separate decision and is not required by this topology.
Do multiple companions guarantee immediate failover?
The inspected reference documents random selection retained with cached video metadata, not a verified transparent-failover guarantee.
Sources
- invidious/config/config.example.ymlSource checked 2026-09-08
- invidious/src/invidious.crSource checked 2026-09-08
- invidious/src/invidious/routes/companion.crSource checked 2026-09-08
- documentation/docs/installation.mdSource checked 2026-09-08