Podgrab: A Self-Hosted Podcast Archiver That Watches RSS Feeds For You

The Problem Podgrab Was Built To Solve

The README is unusually direct about the origin. The author started running during the pandemic, did not want to carry a phone, and loaded episodes onto a smart watch paired with Bluetooth earphones. The obstacle was that most podcast apps do not expose the mp3 files directly. Podgrab exists to put those files on a filesystem you control. That framing matters, because it tells you the intended user is not someone looking for a discovery-first listening app. It is someone who already knows which shows they follow and wants the audio as a file, on a schedule, without opening an app. The README says as much: it works best if you already know which podcasts you want to monitor. There is an iTunes-powered search to add shows, but it is a convenience, not the centre of the design. Secondary features follow from the same goal: OPML import and export so you can move a subscription list from another client, tagging to group shows, and a player that can either play downloaded files or stream from the original source. If your requirement is a hosted podcast service with recommendations and social features, this is the wrong category of tool entirely.

How The Download Loop Actually Works

The architecture visible in the README is a single Go binary: Go with the Gin web framework, GORM as the database layer, and SQLite as the store. There is no external database to run and no message queue. The polling behaviour is governed by one setting, CHECK_FREQUENCY, described as how frequently to check for new episodes and missing files, in minutes, defaulting to 30. That phrase, and missing files, is the interesting part. The scheduler does not only look for new items in a feed; it also reconciles against the filesystem, which is what makes the existing episode file detection feature work. The README claims the tool will not redownload a file if it is already present, even after a fresh install. That is a reconciliation pass, not a download log, which is why it survives a database reset. Two directories carry state: /assets holds the media, /config holds the configuration. The docker-compose example binds both to host paths. Downloads are triggered by the poll, and the player reads either from /assets or from the original enclosure URL, so streaming and local playback are separate paths through the same interface. Filenames can be customised, and there is a roadmap item to append the date, which the author has already marked complete.

Getting It Running With Docker

The README leads with Docker and calls it the easiest route. The minimal form, described as suitable for testing and evaluation, mounts nothing: docker run -d -p 8080:8080 --name=podgrab akhilrex/podgrab. For anything real you want the two volumes, because without them the archive lives inside the container layer: docker run -d -p 8080:8080 --name=podgrab -v "/host/path/to/assets:/assets" -v "/host/path/to/config:/config" akhilrex/podgrab. The compose file in the repository shows the environment block. CHECK_FREQUENCY=240 is the example value, four hours. PASSWORD is commented out; uncommenting it and setting a non-empty value turns on Basic Authentication with the username podgrab. PORT changes the internal port, and the README warns that changing it may require a matching change to your Docker port mapping. Then docker-compose up -d. Two setup notes are easy to miss. If you run behind a reverse proxy, websocket support must be enabled, because the add-to-playlist function depends on it. And the README asks you to visit the settings page once and adjust it before adding podcasts, which implies defaults that are not universally right. There is also a native path for people who do not want Docker: docs/ubuntu-install.md in the repository covers building from source on Ubuntu. The author states a preference for the container.

Where Podgrab Gets In Your Way

The archive model is the biggest constraint, and it is a design choice rather than a bug. Podgrab downloads episodes; it does not manage a retention window. The README lists no per-show storage cap, no delete-after-listen rule, and no automatic pruning. The /assets volume you bind grows with every episode of every feed you add, and the only mechanism described for controlling that is your own filesystem hygiene. The reconciliation pass that prevents redownloads will also notice files you delete, which cuts both ways: removing an episode frees space until the next poll decides it is missing. The README does not say whether a deleted episode is treated as missing and refetched, so treat that as unverified. The roadmap is the second signal. ID3 tag writing, filtering and sorting, and a native installer are all unchecked. If your player depends on consistent metadata tags, the README does not claim Podgrab writes them. Search and sort across a large library are likewise listed as pending, so a library of a few hundred episodes is likely to be navigated by scrolling. Basic Authentication is exactly that: one shared credential, username podgrab, no user accounts, no per-user state. Expose it to the internet without a reverse proxy and TLS at your own risk.

How It Differs From A Podcast Client With Local Storage

The obvious comparison is a desktop podcast client that can also keep downloaded episodes, such as gPodder. The difference is where the logic lives. gPodder is a client: it runs on the machine you listen from, and its download behaviour is tied to that session. Podgrab is a server. It polls on its own clock, writes to a mounted volume, and serves a web interface you reach from any device on the network. That is why OPML import matters here: you bring your subscription list from a client, then the server takes over the fetching. The trade-off is that you lose the tight integration with a local audio player and whatever playback-position sync that client offers. The other comparison worth drawing is against tools that fetch audio on demand and never store it. Podgrab is the opposite: the README describes downloading a complete podcast and archiving it, and the player can stream from the original source as a fallback rather than as the primary mode. If you want to listen without keeping files, a streaming client is lighter. If you want the files, a client that stores them per-device duplicates them on every device you own. Podgrab centralises that one copy.

Keeping It Updated And What GPL-3.0 Means Here

The README carries a developer's note that the project is under active development with frequent releases, and it recommends running watchtower to update the container automatically, or periodically rebuilding the image manually. That is the maintenance story: there is no in-app upgrade path described, and no release list was retrieved for this review, so the practical version you get is whatever the akhilrex/podgrab tag points to at pull time. Pinning a digest is the alternative if you would rather not have the container change under you. Because the image tag is not versioned in the commands shown, an unattended watchtower setup means your running version can change without a changelog in front of you. On licensing, the repository's own README badge and the License section say GPL-3.0, while the badge image link at the top points at an MIT licence URL. That is an inconsistency in the README itself, and the License section text is the one that names GPL-3.0 and points at the LICENSE file. If you plan to redistribute a modified Podgrab, read LICENSE in the repository rather than the badge, and take your own advice on copyleft obligations. This is not legal advice.

Who Should Run Podgrab

The fit is narrow and clear. You follow a fixed set of shows, you want the mp3 files on a disk you control, and you have a device that plays files rather than streams: a watch, a car head unit, an offline laptop. You are comfortable with Docker and a mounted volume, and you accept that the web interface is a means to an end. The misfit is equally clear. If you want discovery, recommendations, cross-device playback position, or a library that stays tidy without you thinking about it, Podgrab will feel like a downloader with a player bolted on, because that is what it is. The author's own roadmap agrees: filtering, sorting, and ID3 tagging are still open items. Before you commit, check three things. Whether your feed volume fits the CHECK_FREQUENCY you set, since every poll of every feed is a network round trip. Whether /assets has the room, since nothing prunes it. And whether your listening device actually accepts the filenames Podgrab produces, which is the whole reason the customisable naming feature exists.

Editorial conclusion

Adopt Podgrab if you already know which feeds you follow and you want the MP3 files on your own disk, for example to sideload onto a watch or a car stereo. Skip it if you need per-episode retention rules, ID3 tag rewriting, or a polished search and sort experience; the roadmap lists ID3 tagging and filtering as unfinished. Before committing, verify the CHECK_FREQUENCY interval against your feed volume and confirm that your /assets volume has room for a full archive, because Podgrab downloads complete episodes by default rather than streaming them on demand.

Official sources

1. akhilrex/podgrab on GitHub
2. Issues
3. License: GPL-3.0
4. README