A self-hosted video downloader with a web interface and API, powered by yt-dlp.
- Download videos and playlists from YouTube and other yt-dlp-supported sites.
- Queue downloads in the background and follow progress in real time.
- Browse download history and retrieve media, subtitles, and thumbnails.
- Manage users and API keys with administrator controls and configurable signup.
- Run the app, API, workers, scheduler, and Redis with Docker Compose.
Use Hermes only for media you have permission to download and reuse. Hermes is intended for lawful use by content creators and does not endorse piracy, freebooting, or bypassing advertising.
hermes_demo.mp4
Install Docker with Compose 2.24.4+ and Git. The commands below build the current checkout so all components use the same source.
git clone https://github.com/TechSquidTV/Hermes.git hermes
cd hermes
cp .env.example .env
# Generate a secret, then set HERMES_SECRET_KEY in .env to the result.
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
nano .env
# Prepare persistent directories for the default container user (UID/GID 1000).
mkdir -p data/downloads data/temp data/data
sudo chown -R 1000:1000 data
docker compose up -d --build --waitOpen the web app and create your first account; it becomes the administrator. Public signup is disabled afterward unless an administrator enables it. You can also seed an administrator before starting the stack.
| Service | Default URL |
|---|---|
| Web app | localhost:3000 |
| Interactive API docs | Swagger UI |
| Alternative API docs | ReDoc |
| API readiness | Readiness check |
The API and Redis stay on the internal Docker network. The app container serves
the UI and proxies /api/* to the API. For HTTPS, put your reverse proxy in front
of the app; see the proxy guide.
Use docker-compose.example.yml and .env.example from the release you deploy.
Prepare the secret and data directories as above, then set HERMES_IMAGE_TAG in
.env to that exact published version without a v prefix. One tag selects the
app, API, worker, and scheduler together.
Release compatibility warning: the 0.6.0 images predate the security and opt-in retention fixes required by these Compose files. Use a release containing those fixes; build the current checkout from source for unreleased changes.
For a new installation with a compatible release:
docker compose -f docker-compose.example.yml pull
docker compose -f docker-compose.example.yml up -d --waitFor an existing installation, use scripts/upgrade.py from the target release:
python3 scripts/upgrade.py 1.2.3 # Replace with the selected published version.The upgrade drains work, backs up the database, migrates it, and checks replacement
services before updating .env. Read the upgrade and recovery guide
first, including its breaking changes and recovery requirements.
The bundled stacks persist the database and scheduler state in data/data,
downloads in data/downloads, and temporary files in data/temp. These directories
must be writable by the backend container user. See the
deployment guide for ownership and backups.
Run one celery_beat scheduler per deployment. It schedules temporary-file and
expired-token cleanup. Download retention is off unless
HERMES_DOWNLOAD_RETENTION_DAYS is set.
After preparing .env and the data directories, start the hot-reload stack:
docker compose -f docker-compose.dev.yml up --build --waitThe development app is at localhost:5173, with API docs at localhost:5173/api/v1/docs. The API is also exposed on port 8000 and Redis on port 6379 for debugging.
See Contributing for native setup, tool versions, checks,
and the pull request workflow. Start branches from main and open PRs to main.
| Guide | Contents |
|---|---|
| Configuration | Environment variables, signup, authentication, and storage settings |
| Deployment | Persistent storage, backups, monitoring, and troubleshooting |
| Reverse proxies | HTTPS, single-domain and separate-domain deployments, and SSE |
| Upgrading | Coordinated upgrades, migrations, and recovery |
| PostgreSQL | Optional PostgreSQL deployment and validation; SQLite is the default |
| Managed files | Media deliverables, sidecars, and path migration requirements |
| Contributing | Development setup, checks, and contribution workflow |
| Release process | Shared versioning, image publication, and release recovery |
| Dependency maintenance | Renovate policy, lockfiles, and dependency validation |
| API | Authenticated usage, endpoint overview, and backend development |
| Frontend | App development, configuration, and generated API types |
For bugs or feature requests, use the issue templates. Include reproduction steps and relevant logs with secrets removed.
Hermes is licensed under AGPL-3.0.