Download videos from YouTube and 1000+ sites with a robust API and beautiful, modern interface

Hermes is a self-hosted video downloader built on yt-dlp.

This tool is designed for content creators who wish to lawfully use freely available media under fair use (best explained by Tom Scott). Hermes does not endorse piracy, freebooting, or using downloads to bypass advertising.

• 🎥 Universal Support - Download from YouTube, Vimeo, TikTok, and 1000+ sites
• ⚡ Background Processing - Queue downloads and process them asynchronously
• ▶️ Playlists - Download entire playlists asynchronously
• 🔒 Secure Authentication - JWT tokens with API key management and admin user control
• 👥 User Management - Admin controls for self-hosted deployments with configurable signup

# Clone the repository
git clone https://github.com/techsquidtv/hermes.git
cd hermes

# Copy environment template (all environment variables are configured in the root .env file)
cp .env.example .env

# Edit .env and set a secure HERMES_SECRET_KEY
nano .env

# Start all services using pre-built images (includes Caddy reverse proxy)
docker compose -f docker-compose.example.yml up -d

That's it! 🎉 Your Hermes instance will be available at:

• Web App: http://localhost:3000
• API Docs: http://localhost:3000/api/v1/docs (via proxy)

For development with hot reload:

docker compose -f docker-compose.dev.yml up

• Dev Server: http://localhost:5173 (Vite with hot reload)
• API: http://localhost:8000 (direct access)

If you prefer to build the images from source or want to modify the code:

# Use the standard docker-compose.yml (builds from source)
docker compose up -d

Hermes offers two deployment approaches:

• Faster startup - No build time required
• Stable releases - Uses tested, published versions
• Smaller downloads - Only pulls necessary images
• File: docker-compose.example.yml
• Public packages - No authentication required

# Uses ghcr.io/techsquidtv/hermes-app:latest and ghcr.io/techsquidtv/hermes-api:latest
docker compose -f docker-compose.example.yml up -d

• Full customization - Modify code and rebuild
• Latest changes - Access to unreleased features
• Development - Perfect for contributors
• File: docker-compose.yml

# Builds images from local Dockerfiles
docker compose up -d

Before starting Docker containers, create the required directories with proper permissions. The API container runs as a non-root user (UID 1000), so mounted volumes must be writable:

# Create directories (paths should match your docker-compose volumes)
mkdir -p ./data ./downloads ./temp

# Set ownership for container user (default UID 1000)
sudo chown -R 1000:1000 ./data ./downloads ./temp

# Or match your current host user (useful for development)
sudo chown -R $(id -u):$(id -g) ./data ./downloads ./temp

# Or use permissive permissions (less secure)
chmod -R 777 ./data ./downloads ./temp

Required directories:

• data/ - SQLite database and persistent data
• downloads/ - Downloaded video files
• temp/ - Temporary files during download

Note: Directory paths depend on your docker-compose configuration. Check the volumes section in your compose file to see where these are mounted from. For example, docker-compose.example.yml might use ./services/hermes/data instead of ./data.

The default setup uses Caddy as a reverse proxy. You can customize it by editing the Caddyfile:

nano Caddyfile
# Add your domain for automatic HTTPS, custom routing, etc.
docker compose restart proxy

Single Domain (Recommended for most users):

• Frontend and API on same domain: hermes.example.com
• API accessible at: hermes.example.com/api/

Separate Domains (Advanced):

• Frontend at: hermes.example.com
• API at: hermes-api.example.com

See the Caddyfile examples for both configurations.

Copy .env.example to .env and configure:

# For single domain
HERMES_ALLOWED_ORIGINS=https://hermes.example.com
VITE_API_BASE_URL=/api/v1

# For separate domains
HERMES_ALLOWED_ORIGINS=https://hermes.example.com,https://hermes-api.example.com
VITE_API_BASE_URL=https://hermes-api.example.com/api/v1

See our Proxy & Deployment Guide for integrating with existing setups (Traefik, nginx, etc.) and deploying with separate subdomains.

Hermes includes security features designed specifically for self-hosted deployments:

By default, anyone with access to your Hermes instance can create an account. For self-hosted deployments, you can restrict signup:

Option 1: First User Becomes Admin (Default)

• The first user to sign up automatically gets admin privileges
• Subsequent users can only sign up if public signup is enabled
• Simple for personal deployments

Option 2: Disable Public Signup

# In your .env file:
HERMES_ALLOW_PUBLIC_SIGNUP=false

• Only administrators can create new accounts via admin panel
• Prevents unauthorized account creation
• Recommended for shared/exposed deployments

Option 3: Pre-seed Initial Admin (Docker-friendly)

# In your .env file:
HERMES_INITIAL_ADMIN_USERNAME=admin
[email protected]
HERMES_INITIAL_ADMIN_PASSWORD=changeme123

• Admin account created automatically on first startup
• Perfect for Docker deployments and automation
• Important: Change the password after first login!

Administrators have access to user management features:

• Create users - Add accounts when public signup is disabled
• Promote/demote admins - Grant admin privileges to trusted users
• Activate/deactivate accounts - Disable access without deleting users
• Delete users - Permanently remove accounts
• Safety checks - Cannot delete yourself or the last admin

Access admin features via: API endpoints at /api/v1/users (see API docs)

1. Set a strong secret key: Generate with python3 -c "import secrets; print(secrets.token_urlsafe(32))"
2. Disable public signup for non-personal deployments: HERMES_ALLOW_PUBLIC_SIGNUP=false
3. Change default credentials if using pre-seeded admin
4. Use HTTPS in production (Caddy provides automatic HTTPS)
5. Restrict CORS origins to your actual domains in .env
6. Keep Hermes updated to get the latest security patches

If you run into problems, please use our issue templates instead of generic issues:

• 🐛 Bug Report - For unexpected behavior
• 🔧 API Issues - Backend problems
• 🎨 Frontend Issues - UI/UX problems
• 🐳 DevOps Issues - Docker/deployment issues

These templates help us help you faster!

For development and contribution purposes:

# Install dependencies
pnpm install

# Set up environment (all environment variables are configured in the root .env file)
cp .env.example .env
# Edit .env with your settings

# Start development servers
pnpm dev

• Configuration Guide - Complete environment variables and settings reference
• Deployment Guide - Docker volumes, production deployment, and troubleshooting
• Contributing Guide - Development workflow, branch strategy, and how to contribute
• Release Process - Version management and release workflow
• API Documentation - Complete API reference and examples
• Frontend Guide - React app development guide
• Interactive API Docs - Live Swagger documentation
• docker-compose.example.yml - Pre-built images deployment configuration

• main - Stable production releases (Docker: latest)
• develop - Integration branch for testing (Docker: develop)
• Feature branches - Your contributions (merge to develop)

This could be you! Bring Hermes to the world by hosting a public instance and getting featured here!