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

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find Medusa in the catalog (browse Media Management or search), and click Install. The dashboard streams the install log live and Medusa appears in your Application Control panel when it finishes. Reinstall, Update, and Remove are available from the same panel.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. See App Management for the full flow.

Install and manage from the CLI

The CLI runs the same install and is suited to automation and scripting:

bash

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

Full flag reference: CLI Reference.

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.

Connect Medusa to rTorrent for torrent search

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

In Medusa, open Config → Search → Torrent Search.
Turn Search torrents ON.
Set Send .torrent files to to rTorrent.
In rTorrent host:port, enter the socket address below, replacing USERNAME with your QuickBox username:

text

scgi:///var/run/USERNAME/.rtorrent.sock

The triple slash is correct

Tip

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

Leave Verify certificate OFF.
(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.
Leave Downloaded files location blank to use rTorrent’s default download directory.
Click Test Connection. A working setup returns:

text

Success: Connected and Authenticated

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

Warning

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

Info

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

Note

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