Follows YouTube channels, downloads new uploads as audio, tags them, and serves a podcast RSS feed per channel to any podcast app on your local network.
Runs as a single Docker container, intended for a Raspberry Pi.
-
Get the compose file and config:
mkdir podmachine && cd podmachine curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/reloadedhead/podmachine/main/docker-compose.yml mkdir -p config curl -fsSL -o config/config.yaml https://raw.githubusercontent.com/reloadedhead/podmachine/main/config/config.example.yaml
-
Edit
config/config.yaml: setbase_urlto an address your podcast apps can reach on your LAN (e.g.http://podmachine.local:8000orhttp://<pi-ip>:8000), and list the channels you want to follow. Thischannels:list is only a one-time bootstrap — the first time podmachine starts with an empty channel database, it imports this list and then ignores it from then on. After that, add/remove channels from the admin UI (see below) instead of editing config.yaml and restarting. -
Pull and run:
docker compose pull docker compose up -d
That's it — podmachine polls and downloads automatically from here on
(poll_interval_minutes, starting immediately). Point a podcast app at:
http://<pi-ip-or-podmachine.local>:8000/feeds/<channel-slug>.xml
To update later, re-run step 3.
Every push to main that touches src/, Dockerfile, or
requirements.txt builds and publishes a multi-arch (amd64 + arm64)
image via GitHub Actions to ghcr.io/reloadedhead/podmachine:latest
(.github/workflows/docker-publish.yml) — public, no login needed to
pull.
| Field | Description |
|---|---|
poll_interval_minutes |
How often to check channels for new uploads |
base_url |
LAN-reachable base URL used in generated feed/enclosure links |
channels[].id |
YouTube channel ID (UC...) — bootstrap only, see above |
channels[].name |
Display name used as podcast/episode metadata — bootstrap only |
channels[].slug |
URL-safe identifier, used in feed and file paths — bootstrap only |
channels[].category |
Required. One of Apple's fixed iTunes/Apple Podcasts categories — bootstrap only for the initial import; editable afterwards from the channel's admin page |
retention.strategy |
none (default) or count — bootstrap only, see above. See "Episode retention" below |
retention.keep_latest |
Episodes to keep per channel when strategy: count — bootstrap only |
channels[].retention |
Optional per-channel override, set from a channel's admin page — replaces the global retention policy entirely for that channel, not merged |
admin.password |
Optional. Set to enable the admin web UI at /admin/, protected with this shared HTTP Basic auth password. Unset disables /admin/ entirely (404) |
| Endpoint | Description |
|---|---|
GET /healthz |
Liveness check |
GET /channels |
Per-channel status: baseline state, poll failures, video counts |
POST /run |
Force a full poll + download cycle immediately |
POST /poll |
Poll for new videos only, without downloading |
POST /process |
Download/tag anything already pending, without polling |
GET /feeds/<slug>.xml |
Podcast RSS feed for a channel |
GET /media/<slug>/<file> |
Episode audio file |
GET /artwork/<slug>.jpg |
Channel cover art |
GET /admin/ |
Admin dashboard (channel status, episode list, manual poll/process) — only if admin.password is set |
GET /admin/settings |
Admin settings page (default retention policy) — only if admin.password is set |
Set admin.password in config.yaml to enable a small dashboard at
/admin/ — per-channel status (last poll, failures, backoff, episode
counts), a per-channel episode list with any error messages, and buttons
to trigger a poll or a download/tag pass by hand. From the dashboard you
can also add a channel (a YouTube channel ID, plus a required iTunes
category picked from Apple's fixed list — display name and slug are
fetched/generated automatically, or you can set them by hand) and remove
one;
from a channel's detail page you can retry a failed episode, delete an
episode (removes the file, keeps the tombstoned row so it isn't
re-downloaded), change its iTunes category, and override its retention
policy. The Settings page has
a "Default retention" setting — the app-wide policy every channel falls
back to unless it has its own override. All of this is stored in the
database, not config.yaml — no restart needed. It's server-rendered
HTML with htmx for the interactive bits (auto-refreshing
tables, in-place button actions) — no JS framework, no build step; htmx
itself is vendored into the image rather than loaded from a CDN. It's
protected with HTTP Basic auth using the shared password (the rest of the
API — feeds, media, JSON endpoints — stays unauthenticated, as it always
has, since podcast apps need to reach it without a login prompt).
Off by default — downloaded episodes accumulate forever unless you opt
in. Set the default policy from the admin Settings page's "Default
retention" card (or bootstrap it via config.yaml's retention: block, see
above) to keep only the N most recent episodes per channel:
retention:
strategy: count
keep_latest: 20A channel can override this from its own admin page (replaces
the global one entirely, not merged). Deleting an episode removes the
mp3 and marks it deleted in the database — the record itself is kept
permanently so it's never mistaken for a new upload and redownloaded.
age (delete anything older than N days) and size (cap total storage)
strategies are planned but not built yet; see
docs/retention.md for the full design of all
three, including why deletion works the way it does.
Run tests inside a container matching the production Python version (the host machine's Python may be newer than what pinned deps have wheels for):
docker run --rm -v "$(pwd)":/app -w /app python:3.12-slim-bookworm \
bash -c "pip install -r requirements-dev.txt && pytest -q"- Retry with backoff. A failed download is retried up to 3 times (2s,
4s backoff) before being marked
failed. YouTube 403s are often transient — this was verified directly: a manual retry during testing succeeded immediately, and the automated retry logs the same recovery pattern in production use. - Long-range retry. Some 403s aren't transient within a single cycle
but do resolve over days, as YouTube's bot-detection rollouts are
partial and evolving (see
docs/known-issues.md). Anything stillfailedgets automatically requeued once a day, capped at 5 attempts, so recovery doesn't depend on someone noticing and manually reprocessing. - Per-channel circuit breaker. A channel that fails to poll 5 times in
a row (bad channel ID, deleted channel, persistent network issue) is left
alone for 1 hour instead of being retried every cycle. Each feed request
is itself retried up to 3 times (2s, 4s backoff) on 404/429/5xx and
connection errors first, since YouTube's RSS endpoint returns transient
404s for valid channels. The failure count resets on the next successful
poll, or when a backoff expires. Visible in
/channelsviaconsecutive_poll_failures,backed_off_until, andlast_poll_error. - Politeness. Channels are polled sequentially with a randomized 1-4s gap between them, not in parallel; downloads use a similar gap plus a ~2MB/s rate limit. None of this is about bandwidth — it's about not looking like a script hammering YouTube as fast as possible.
- Non-root, read-only container. The container runs as an unprivileged
user (uid 1000) with a read-only root filesystem — only
/dataand/tmp(tmpfs) are writable. Verified end-to-end under both restrictions: real downloads, tagging, and feed/media serving all still work; writing anywhere else in the container fails as intended. - Only videos published after a channel is added are downloaded — no history backfill.
- YouTube Shorts are skipped, detected directly from the RSS entry's link
(
/shorts/...vs/watch?v=...) — no extra request needed. - The Docker image bundles Deno as yt-dlp's JS runtime, required for YouTube's signature extraction — without it, downloads fail with a misleading HTTP 403.
- Feed artwork. Each channel's real avatar is fetched once (via a cheap
yt-dlp metadata-only call that doesn't enumerate any videos), cached to
/data/artwork/<slug>.jpg, and served at/artwork/<slug>.jpgfor use as the podcast's cover art — not hotlinked from Google's CDN. Until it's fetched (or if the fetch ever fails), the feed falls back to borrowing the most recent episode's thumbnail so it's never imageless. Per-episode artwork always uses that episode's own real thumbnail. - Each channel has its own iTunes category, required when it's added and
changeable afterwards from the channel's admin page. It's constrained to
Apple's fixed top-level category list (both in the Pydantic model and via
a SQL
CHECKconstraint on thechannelstable) since Apple rejects anything else; subcategories aren't supported yet. - For personal/private LAN use only — don't expose this outside your network or redistribute the feeds.
yt-dlp is pinned to a specific tested version in requirements.txt
because YouTube changes frequently enough that an untested update can
silently break downloads. Signs you need to bump it:
- Downloads that used to work now fail consistently (not just an occasional 403 that clears on retry — see the retry/backoff logs)
/channelsshows a channel's episodes stuck infailedacross multiple cycles
To update:
# find the latest version
docker run --rm python:3.12-slim-bookworm bash -c \
"pip install --quiet yt-dlp && python3 -c 'import yt_dlp; print(yt_dlp.version.__version__)'"Edit the yt-dlp==... line in requirements.txt to that version, then
rebuild (docker compose up --build -d) and check /channels after the
next cycle. If it doesn't help, it's usually a matter of days before
yt-dlp ships a fix — try again then.

