Deploy and Host YT Zero on Railway

YT Zero is a self-hosted YouTube subscription inbox. It follows the public feeds of the channels you care about and gives you one chronological list of their videos — no Google account, no YouTube Data API key, no recommendation algorithm. Subscriptions, watch progress, playlists and tags live in your own database, on your own disk.

This template deploys it with a household login already in place. YT Zero itself ships with authentication set to none and offers no environment variable that turns a login on, so a stock deploy answers every stranger who has the URL. Here the login is written into the database before the port is ever bound, from a password Railway generates for this deployment.

About Hosting YT Zero

One container, one volume, and nothing else. YT Zero serves its own frontend, refreshes channel feeds on an adaptive background schedule, and keeps subscriptions, watch history, playlists, profile avatars and the thumbnail cache in a local SQLite database under /data. There is no separate worker, no queue and no cache server to run alongside it. PostgreSQL is supported later as a migration, not required now.

Because it reads public channel feeds rather than talking to a Google account, there is nothing to authorize and no API quota to manage. yt-dlp and ffmpeg are bundled, so the optional download feature works without adding anything to the stack.

Why Deploy YT Zero on Railway?

Railway gives this app exactly what it needs and nothing it does not: a container, a persistent disk, a public domain and a certificate. There is no reverse proxy to configure, no database server to provision and no port mapping to reason about.

The one thing Railway also does is make the URL public the moment the deploy goes green, which is why this template does not leave the login for you to set up afterwards.

Common Use Cases

Following YouTube channels without a Google account, an algorithmic home feed, or a watch history that follows you around the web.
A household install with a profile each, including child profiles with daily watch-time limits, subscribed-content-only mode and a settings PIN.
Offline and low-bandwidth viewing, where scheduled videos are downloaded ahead of time and played back from local disk.

Dependencies for YT Zero Hosting

A container runtime and one persistent disk. SQLite is built in.
Outbound internet access to fetch public channel feeds, video metadata and thumbnails.

Deployment Dependencies

Upstream project: https://github.com/Pelski/ytzero
Upstream image: ghcr.io/pelski/ytzero (pinned here to 2026.08.16)
This template's image: ghcr.io/bon5co/ytzero-railway (source)
License: AGPL-3.0-only

Implementation Details

The login is seeded before the first request is served. YT Zero stores its auth method in the auth_method setting and defaults it to none; the only related environment variable in the code, YTZERO_AUTH_DISABLE, turns authentication off. While auth_method is none, isPrimaryUser() is satisfied by any caller, so an anonymous visitor can not only read your feed, settings and profiles — they can PUT /api/auth/config to set their own password and POST /api/auth/method to activate it, at which point the instance is theirs and you are locked out until you redeploy with YTZERO_AUTH_DISABLE=1.

This template's entrypoint writes the shared login into the database in a separate process that must finish before the server binds its port, so there is no window in which an unauthenticated instance is reachable. Verified on the live deploy: /api/settings, /api/videos and /api/profiles answer 401 anonymously, PUT /api/auth/config and POST /api/auth/method answer 403, and the generated password logs in.

Sign in with username admin and the generated YTZERO_ADMIN_PASSWORD, which you can read in the service's Variables tab. Change it in Settings > Authentication whenever you like — the seed only ever acts when no auth method has been configured, so switching to per-profile logins, OIDC or a proxy header is your call and is never overwritten. An empty YTZERO_ADMIN_PASSWORD makes the container refuse to boot rather than come up open.

The image is pinned, not tracking latest. YT Zero ships builds almost daily and runs migrations forward on boot, so an unpinned redeploy is an unrequested upgrade with no way back. Change the tag on your own service when you want to move.

Everything stateful is on the volume. DOWNLOAD_COOKIES_DIR and RESTORE_SESSION_DIR are the two paths the upstream image does not point at /data itself; without them, per-profile YouTube cookies and staged backup restores sit on the disposable container layer and vanish on redeploy.

APP_URL is set to this deployment's Railway domain and is used as the sign-in redirect origin for single sign-on and passkeys. On a custom domain, update it and add WEBAUTHN_RP_ID.

Getting started. The app boots empty. Add channels under Settings > Channels by URL, by OPML file, or by importing subscriptions.csv from Google Takeout. The feed fills within a minute or two, then refreshes on a schedule that adapts to how often each channel uploads.

Downloads are off by default. When you turn them on, files go to /data/downloads — set a retention policy and a storage cap in the same settings screen, or grow the volume.