No Root Seedbox Install

No-root install on a shared seedbox (Whatbox & similar)

The README's bare-metal instructions assume pipx and, if something goes wrong, sudo. Neither is available on a shared seedbox like Whatbox — you get an unprivileged shell account, no package-manager access, and often a Python install that actively refuses pip install outside a virtual environment. This page is the no-root path around that, start to finish.

Step 1 — create a venv

python3 -m venv ~/myenv
source ~/myenv/bin/activate

This is worth doing even before you hit any errors: a venv gives you your own isolated pip, sidesteps the "externally managed environment" refusal system Python installs enforce (PEP 668 — see below), and doesn't touch anything outside ~/myenv. Name/location is up to you; the rest of this guide assumes ~/myenv.

If python3 -m venv itself fails (e.g. ensurepip is not available — some minimal distro Python builds strip it), create the venv without pip and bootstrap it manually:

python3 -m venv --without-pip ~/myenv
source ~/myenv/bin/activate
curl -sL https://bootstrap.pypa.io/get-pip.py | python

If you skip the venv and try pip install against the system Python, you'll hit one of two errors depending on the host:

• ModuleNotFoundError: No module named 'pip' — the system Python has no pip at all. python3 -m ensurepip --user sometimes fixes this; if that also fails, use the get-pip.py bootstrap above.
• error: externally-managed-environment — pip exists but Gentoo (or another distro following PEP 668) refuses to let you install into the system Python. There is no --user workaround for this one — a venv is the actual fix, not a bypass.

Once the venv is active, python, pip, and any installed console scripts (collapsarr included) all resolve inside ~/myenv — no root needed for any of it.

Step 2 — install Collapsarr

Stable release, with the venv active:

pip install collapsarr

Beta build (testing an upcoming change ahead of a tagged release): see Beta builds for how to find the right .whl on the latest beta-<sha> GitHub Pre-release. A seedbox shell has no browser, so download it with curl instead of clicking it — set the asset URL in a variable first and echo it back before you use it, so a typo or an empty copy/paste fails loudly instead of silently downloading nothing (or the wrong thing):

URL="<paste the .whl asset URL from the Pre-release page>"
echo "$URL"    # sanity-check it's non-empty and actually ends in .whl
curl -sLO "$URL"
pip install ./collapsarr-*.whl

If $URL echoes empty, you copied the wrong link — go back to the Releases page, open the beta-<sha> Pre-release, and right-click the .whl asset itself (not the release page link) to copy its direct download URL.

Upgrading later (same venv, active): pip install --upgrade collapsarr for stable, or re-download and re-run pip install ./collapsarr-*.whl for a newer beta.

FFmpeg still needs to be on PATH — see the README's Requirements section. If your seedbox doesn't have it and you can't install it yourself, ask support — you can't apt/emerge it without root.

Step 3 — run it, and keep it running after you disconnect

Just running collapsarr in your SSH session dies the moment you disconnect — closing the session sends SIGHUP to whatever's still in the foreground. Without root you don't get a systemd service (see the README's Running on startup section for the systemd version if you do have one), so detach it yourself instead:

screen or tmux (recommended — lets you reattach and watch the logs later):

screen -S collapsarr
source ~/myenv/bin/activate
collapsarr
# Ctrl-A then D to detach — the SSH session can close now, it keeps running

Reattach any time with screen -r collapsarr. If tmux is what your host has instead: tmux new -s collapsarr / tmux attach -t collapsarr.

nohup + disown (simpler, but no session to reattach to — you're reading the log file for status):

source ~/myenv/bin/activate
nohup collapsarr > ~/collapsarr.log 2>&1 &
disown

Known limitation of both: neither restarts Collapsarr if it crashes — that's what systemd's Restart=on-failure gives you on a host where you control the service manager. Here, recovery is manual: reattach the screen/tmux session (or check ~/collapsarr.log) and start it again if it's down.

Where things live

No COLLAPSARR_DATA_DIR override needed — it defaults to ~/.local/share/collapsarr (the SQLite database, backups, logs), which works fine without root. Open http://<your-seedbox-host>:8282 once it's running; see the README's Configuration section for the full environment-variable list if you want to change the port or anything else.