Skip to Content
DocsApplicationsMedia ManagementMedusa
Medusa

Medusa

Video File Manager for TV shows with automatic episode handling and manual search

Overview

Medusa is a Video File Manager for TV shows. It watches for new episodes of your favorite shows, performs automated handling when they are posted, and includes manual search capabilities. QuickBox installs Medusa under /opt/username/Medusa, manages a Python virtual environment in /opt/username/lib/python/Medusa/.venv, and stores Medusa configuration in /home/username/.config/Medusa/config.ini.

Key features

Here is what QuickBox sets up for Medusa based on the install and service templates.

🌐 Path-based web access

Nginx exposes Medusa at /username/medusa and proxies to 127.0.0.1:8049 by default.

🧩 Systemd-managed service

Runs as medusa@username with the data directory and config under /home/username/.config/Medusa.

🔑 Dashboard-visible API key

The API key is read from /home/username/.config/Medusa/config.ini and shown in the QuickBox dashboard widgets.

🗂️ Repository-based install

QuickBox installs Medusa from the pymedusa/Medusa repository and tracks the release version.

When to use it

Use Medusa when you want automated TV show monitoring with manual search on top of QuickBox-managed installs.

Good fit when

  • You want a TV show manager that watches for new episodes automatically
  • You prefer a web UI served behind QuickBox nginx
  • You need manual search in addition to automatic processing

What QuickBox provides

  • Medusa watches and processes new episodes once they are posted
  • QuickBox maps Medusa to a path-based URL and manages the service
  • The dashboard surfaces the port and API key for quick access

Installation

QuickBox supports installing Medusa by CLI or from the dashboard, depending on your workflow.

Install from the QuickBox CLI

QuickBox provides standard Medusa lifecycle commands through qb.

qb install medusa -u username
qb reinstall medusa -u username
qb update medusa -u username
qb remove medusa -u username

You can also run qb help medusa for command help specific to Medusa.

Install from the Dashboard

In the Package Manager list, Medusa shows an Install action when it is not present. After installation, the UI shows Installed with a Reinstall option for the same entry.

Access and authentication

Medusa access details are defined by the QuickBox nginx template and the Medusa config file.

URL / route

Medusa is exposed as a path-based route at /username/medusa. The default web port is 8049, and the Medusa config sets the web host to 127.0.0.1 with the web root /username/medusa.

Credentials / tokens

The nginx template enforces HTTP Basic Authentication using /etc/htpasswd.d/htpasswd.username. Medusa’s API key is stored in /home/username/.config/Medusa/config.ini and surfaced in the QuickBox dashboard widgets.

Security notes

Because the nginx location block requires basic auth, the htpasswd file must remain in place. Keep the route in Medusa’s web_root aligned with the nginx location to avoid mismatched paths.

SSL and subdomain setup

The Medusa nginx template is path-based (/username/medusa) and sets proxy headers such as X-Forwarded-Proto and X-Forwarded-Port (443). No Medusa-specific subdomain configuration is defined in the Medusa nginx template.

Configuration and files

These paths are created or referenced during installation and service setup.

/
opt/
└── username/
│ ├── Medusa/# Application install directory
│ └── lib/
│ │ └── python/
│ │ │ └── Medusa/
│ │ │ │ └── .venv/# Python virtual environment
home/
└── username/
│ ├── .config/
│ │ └── Medusa/
│ │ │ └── config.ini# Medusa configuration and API key
│ └── tmp/
│ │ └── Medusa/# Temporary runtime directory
etc/
├── nginx/
│ └── software/
│ │ └── username.medusa.conf# Medusa nginx location block
├── systemd/
│ └── system/
│ │ └── medusa@username.service# Systemd service unit
└── htpasswd.d/
│ └── htpasswd.username# HTTP Basic Auth credentials

Common tasks

These tasks are surfaced in the QuickBox dashboard service controls for Medusa.

  • Start and stop the Medusa service using the dashboard controls tied to the medusa service.
  • Use the Refresh action in the service list when Medusa is already running.
  • Launch Medusa directly from the dashboard link when the service is active.

Medusa can send matched releases straight to your local rTorrent. The connection is configured entirely inside the Medusa web UI.

  1. In Medusa, open Config → Search → Torrent Search.
  2. Turn Search torrents ON.
  3. Set Send .torrent files to to rTorrent.
  4. In rTorrent host:port, enter the socket address below, replacing USERNAME with your QuickBox username:
scgi:///var/run/USERNAME/.rtorrent.sock

The triple slash is correct

The prefix is scgi:// and the path begins with /var/run/..., which produces scgi:///var/run/.... Do not remove the extra slash.

  1. Leave Verify certificate OFF.
  2. (Optional) In Add label to torrent, enter a label such as medusa so new downloads are tagged in rTorrent. Add label to torrent for anime works the same way for anime releases.
  3. Leave Downloaded files location blank to use rTorrent’s default download directory.
  4. Click Test Connection. A working setup returns:
Success: Connected and Authenticated
  1. Click Save Changes.

Once saved, Medusa will hand off matched .torrent files to rTorrent for downloading.

Best practices

Follow these guardrails to keep the Medusa route and authentication in sync with QuickBox.

Do

  • Keep the Medusa web root aligned with the nginx location: /username/medusa.
  • Store and manage the API key in /home/username/.config/Medusa/config.ini so the dashboard can display it.

Don't

  • Do not remove /etc/htpasswd.d/htpasswd.username while basic auth is enabled for Medusa.
  • Do not change the Medusa web port without updating the nginx proxy port in the Medusa nginx template.

Troubleshooting

Use these checks when Medusa does not load or the dashboard shows missing details.

Medusa prompts for credentials or denies access

Confirm that /etc/htpasswd.d/htpasswd.username exists and matches the credentials you expect. The Medusa nginx template enforces basic auth for every request.

Medusa page does not load

Verify that the Medusa config has web_host = 127.0.0.1 and web_port = 8049, and that the nginx location is /username/medusa with the same web root.

Dashboard shows API Key Not Generated

Check the api_key value in /home/username/.config/Medusa/config.ini. The dashboard reads the key directly from this file.

Resources

Official upstream resources for Medusa.

Medusa resources

Medusa on GitHub

Source repository referenced by QuickBox

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support
Feature Previews
Community Configs
Active Discussions
Join Discord Server
LidarrMylar3