Installation

You can run PodVault in two ways:

• Docker (recommended). One container, one data volume, no Python setup. The image is published for linux/amd64 and linux/arm64.
• From source. Install the Python package with pip and run the podvault command directly.

Home network only

PodVault is designed for a local or home network. Don't expose it directly to the internet (port forwarding, a public server, etc.). It hasn't been through any security audit or penetration testing. The optional login keeps other people on your network out; it doesn't make PodVault safe to publish. To reach it from outside your home, use a VPN such as WireGuard or Tailscale. More in Security.

Docker

You need Docker, or Docker with the Compose plugin. Then follow the Quick start:

docker run -d --name podvault \
  -p 8000:8000 \
  -v ./data:/app/data \
  -e PODVAULT_USERNAME=admin \
  -e PODVAULT_PASSWORD=change-me \
  --restart unless-stopped \
  martitoci/podvault:latest

Everything PodVault stores (database, downloads, feed list, backups) lives in /app/data inside the container, mounted from ./data on the host. See Docker for volumes, updating, the health check and running the CLI inside the container.

Building the image yourself

The source repository includes a Dockerfile and a docker-compose.yml that builds from source:

git clone https://github.com/chmedinap/PodVault.git
cd PodVault
docker compose up -d --build

To stop it: docker compose down. The image is based on python:3.11-slim and runs podvault serve --host 0.0.0.0 --port 8000.

From source

Requirements

• Python 3.7 or higher
• pip

Install

git clone https://github.com/chmedinap/PodVault.git
cd PodVault
pip install -e .

This installs the podvault command and its dependencies: pandas, numpy, feedparser, requests, mutagen (tags), tqdm (progress bars), and fastapi, uvicorn, jinja2 and python-multipart (web interface).

Run the web interface

This computer only

podvault serve

The dashboard opens at http://127.0.0.1:8000. No login is needed when only this computer can reach it.

Other devices on your network

PODVAULT_USERNAME=admin PODVAULT_PASSWORD='a-long-password' \
  podvault serve --host 0.0.0.0

Binding to 0.0.0.0 makes PodVault reachable from other machines, so turn on the login. podvault serve warns you if you bind to a non-local address without one.

Use --host and --port to change the address. Starting the server also starts the auto-refresh scheduler.

Or work from the command line

Without Docker, PodVault keeps its files in the current directory: podvault_data.db, downloads/ and feeds.txt. You can manage everything from the terminal:

# Add a feed and read its episodes
podvault add https://feeds.example.com/podcast.rss

# See your podcasts
podvault list

# Download the newest episode, or all of them
podvault download-last podcast_name
podvault download podcast_name

You can also list feeds in feeds.txt, one RSS URL or Apple Podcasts link per line, and run podvault process-feeds. See the command-line reference.

All paths and settings can be changed with PODVAULT_* environment variables. See Configuration.