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.

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