Podhound

Mon, 01 Jan 0001 00:00:00 +0000

gPodder API v2 Endpoints#

Podhound implements the essential gPodder API v2 endpoints to allow synchronization with standard podcatchers.

All API endpoints require HTTP Basic Auth (username + password).

Authentication#

Method	Endpoint	Description
`POST`	`/api/2/auth/<username>/login.json`	Authenticate and receive a session cookie. Also accepts JSON body `{ "password": "..." }`.

Devices#

Method	Endpoint	Description
`GET`	`/api/2/devices/<username>.json`	List registered devices for the user.
`POST`	`/api/2/devices/<username>/<device_id>.json`	Register or update a device.

Subscriptions#

Method	Endpoint	Description
`GET`	`/api/2/subscriptions/<username>/<device>.json`	Get the list of podcast subscriptions.
`POST`	`/api/2/subscriptions/<username>/<device>.json`	Update subscriptions. Body: `{ "add": [...], "remove": [...] }`.

Episode Actions#

Method	Endpoint	Description
`GET`	`/api/2/episodes/<username>.json`	Get episode actions. Supports `?since=<timestamp>` and `?podcast=<url>` query params.
`POST`	`/api/2/episodes/<username>.json`	Upload episode actions. Body: array of `EpisodeActionPayload` objects.

Health Check#

Method	Endpoint	Description
`GET`	`/` or `/health`	Returns service status and API version info.

Mon, 01 Jan 0001 00:00:00 +0000

Command Line Interface (CLI)#

Podhound provides a CLI for server management.

Usage#

# Via Bun (development)
bun run src/main.ts <domain> <action> [args...]

# Via compiled binary
./dist/podhound <domain> <action> [args...]

User Management#

List all users#

# Via Bun (development)
bun run src/main.ts users list

# Via compiled binary
./dist/podhound users list

Displays a table of all registered users.

Create a new user#

# Via Bun (development)
bun run src/main.ts users create <username> <password>

# Via compiled binary
./dist/podhound users create <username> <password>

Manually creates a new user account.

Mon, 01 Jan 0001 00:00:00 +0000

Developer Guide#

Prerequisites#

Bun installed (v1.x or newer).

Steps to Run#

Clone the repository and navigate into the directory:

git clone https://github.com/svyatoslav-kubakh/podhound.git
cd podhound

Install dependencies:
```
bun install
```
Start the server in development mode (with hot-reloading):
```
bun start:dev
```
The server will start listening at http://localhost:8080.
Run automated test suite:
```
bun test
```

Lint and auto-fix code style:

bun run lint # check only
bun run lint:fix # auto-fix

Build a standalone executable binary:
```
bun run build
./dist/podhound
```

Project Structure#

src/
├── config/ # App configuration (env variables)
├── db/ # Database client, migrations
│ └── migrations/ # SQL migration files
├── routes/ # HTTP and CLI routing
│ ├── api/ # API sub-routers (auth, devices, subscriptions, episodes)
│ └── cli/ # CLI sub-routers (user management)
├── services/ # Business logic (auth, users, subscriptions, episodes)
├── types/ # Shared TypeScript interfaces
└── main.ts # Application entry point

For a full list of available settings, please refer to the Environment Variables documentation.

Mon, 01 Jan 0001 00:00:00 +0000

Configuration / Environment Variables#

Podhound is configured entirely via environment variables.

Variable	Description	Default Value
`PORT`	HTTP port the server listens on	`8080`
`DATABASE_PATH`	Path to the SQLite database file	`data/podhound.db` (or `/app/data/podhound.db` in Docker)
`AUTO_REGISTER`	Automatically register new users upon first login (`true` or `false`)	`false` (`true` in Docker)
`LOG_LEVEL`	Minimum log level (`debug`, `info`, `warn`, `error`, `silent`)	`info` (`silent` in test)

Mon, 01 Jan 0001 00:00:00 +0000

AntennaPod Setup Guide#

Open AntennaPod ➔ Settings ➔ Synchronization.
Select gPodder.net (or Custom Server) as the provider.
Enter your server URL: http://<YOUR-SERVER-IP>:8080.
Enter your username and password (on first login, if AUTO_REGISTER is enabled, Podhound will automatically create your account).
Done! Your podcast subscriptions and playback positions will now sync seamlessly across devices.

Compatible Clients

Mon, 01 Jan 0001 00:00:00 +0000

📱 Compatible Podcast Clients#

Podhound is compatible with any podcast player that supports the gPodder API v2 protocol.

📱 AntennaPod (Android)#

AntennaPod is an open-source, feature-rich podcast manager for Android with built-in gPodder API v2 support.

Platform: Android
License: Open Source (GPLv3)
Downloads: Google Play | F-Droid | Website
Setup Guide: See our AntennaPod Setup Guide.

💻 gPodder Desktop#

The original cross-platform podcast aggregator.

Platform: Windows, macOS, Linux
License: Open Source (GPLv3)
Downloads: gPodder Releases
Setup: In gPodder preferences, choose gPodder.net, click Advanced, and set the Custom Server URL to your Podhound server.

🐧 Kasts (KDE / Linux)#

A modern podcast player for Linux desktop and mobile devices built with Kirigami.

Docker Deployment Guide

Mon, 01 Jan 0001 00:00:00 +0000

Docker Deployment Guide#

Deploy Podhound using Docker or Docker Compose in seconds.

Use our Interactive Config Generator to generate a custom docker-compose.yml or docker run command with 1 click.

Option A: Via `docker run`#

Run the container by mapping the HTTP port and persisting the database volume:

docker run -d \
 --name podhound \
 -p 8080:8080 \
 -v podhound_data:/app/data \
 -e PORT=8080 \
 -e DATABASE_PATH=/app/data/podhound.db \
 -e AUTO_REGISTER=true \
 --restart unless-stopped \
 skubakh/podhound:latest

Option B: Via `docker-compose.yml`#

Create a docker-compose.yml file:

FAQ & Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

❓ Frequently Asked Questions (FAQ)#

Find quick answers to common questions about running, configuring, and maintaining Podhound.

📱 How do I connect AntennaPod on Android?#

Open AntennaPod -> Settings -> Synchronization.
Choose gPodder.net / Custom Server.
Enter your Podhound server URL (e.g. http://192.168.1.100:8080 or https://podhound.yourdomain.com).
Enter your username and password.
Tap Log In and select your device name.

🔒 How do I disable new user registrations?#

Set the AUTO_REGISTER environment variable to false in your Docker or binary setup:

Podhound

gPodder API v2 Endpoints#

Authentication#

Devices#

Subscriptions#

Episode Actions#

Health Check#

Command Line Interface (CLI)#

Usage#

User Management#

List all users#

Create a new user#

Developer Guide#

Prerequisites#

Steps to Run#

Project Structure#

Configuration / Environment Variables#

AntennaPod Setup Guide#

Compatible Clients

📱 Compatible Podcast Clients#

📱 AntennaPod (Android)#

💻 gPodder Desktop#

🐧 Kasts (KDE / Linux)#

Docker Deployment Guide

Docker Deployment Guide#

Option A: Via docker run#

Option B: Via docker-compose.yml#

FAQ & Troubleshooting

❓ Frequently Asked Questions (FAQ)#

📱 How do I connect AntennaPod on Android?#

🔒 How do I disable new user registrations?#

Option A: Via `docker run`#

Option B: Via `docker-compose.yml`#