CleanCut Suite

CleanCut Suite help

Every fix here is also in the app: open Help and scroll to Troubleshooting. The Run check-up button on that page tests everything at once and links straight to the right fix.

Each problem starts with what it means, in plain words. The fixes are in order: try the first one first. Restarting CleanCut never loses anything.

Pick what's happening

Words you'll see

New to home servers? These are the words that come up most. Each one is explained again where it appears.

  • Server: the computer at home that runs CleanCut all day.
  • Dashboard: CleanCut's page in your web browser, at http://<your-server>:8585.
  • App store: what you installed CleanCut with (CasaOS, Unraid, Synology Container Manager, TrueNAS or Docker). It starts, stops, restarts and updates CleanCut.
  • Container: the sealed box CleanCut runs in. Everything it needs is inside, kept separate from the rest of your server.
  • IP address: a device's number address on your home network, such as 192.168.1.50.
  • Port: the number after the colon in an address (:8585). It tells the server which app you want.
  • VPN: a private, scrambled connection through a VPN company. CleanCut only downloads through it.
  • Search site (also called an indexer): a website that lists what can be downloaded. CleanCut searches them for you.
  • Sonarr, Radarr, Prowlarr, qBittorrent and Bazarr: well-known apps built into CleanCut that find TV shows, find movies, search the search sites, download, and fetch subtitles. On their own they take hours to set up and link together. CleanCut does that for you and keeps them out of sight.
  • API key: a long password that lets one app talk to another. Keep it private.
  • Tailscale: a free app that links your phone to your server privately, so CleanCut works away from home.
  • Logs: a running diary of what an app is doing. Useful when you ask for help.
  • Terminal: a window where you type commands. Only a few rare fixes below need one.

I can't open the dashboard

What this means: the dashboard is CleanCut's page in your web browser. When it won't open, the address is usually slightly off, CleanCut is still starting, or your phone or computer isn't on the same network as the server (the computer that runs CleanCut).

  1. Check the address. It's http://<your-server>:8585. Replace <your-server> with your server's IP address (its number address on your home network, such as 192.168.1.50) or its name. The :8585 part is the port: the number that tells the server you want CleanCut. If your app store gave CleanCut a different port, use that number instead.
    • CasaOS: click the CleanCut icon on your CasaOS dashboard. Or take the address you use for CasaOS and add :8585 to the end, for example http://192.168.1.50:8585.
  2. Type http://, not https://. Some browsers add the s by themselves. If the page says it can't connect securely, type the whole address again, starting with http://.
  3. Wait two minutes after installing, starting or updating CleanCut. It starts its built-in apps in the background first, and the page appears when they're ready.
  4. Check your network. Your phone or computer must be on the same Wi-Fi as the server. On a phone, turn mobile data off for a moment to be sure. Away from home, use Tailscale (see Using CleanCut away from home at the end of this guide).
  5. Restart CleanCut. It's like switching it off and on again. Nothing is lost: it picks up exactly where it left off.
    • CasaOS: on the CasaOS dashboard, right-click CleanCut's icon (or click the ⋮ dots on the icon), then click the round-arrow restart button at the bottom of the menu.
    • Unraid: Docker tab → click CleanCut's icon → Restart.
    • Synology: Container Manager → Container → select clean-media → Action → Restart.
    • TrueNAS: Apps → select clean-media → Restart.
    • Docker: in a terminal (a window where you type commands), type docker restart clean-media.
  6. Still nothing? Look at CleanCut's logs. Logs are a running diary of what CleanCut is doing, kept by your app store.
    • CasaOS: right-click CleanCut's icon (or click its ⋮ dots) → Settings → Terminal and Logs at the top → Logs tab.
    • Unraid: Docker tab → click CleanCut's icon → Logs.
    • Synology: Container Manager → Container → open clean-media → its Log tab.
    • Docker: in a terminal, type docker logs --tail 50 clean-media.
  7. Copy the last 20 or so lines and send them with your question. Our email address is on shop.harrelsons.org/cleancut, or reply to the email your license key came in.

I forgot my parent password, or I'm locked out

What this means: the parent password keeps kids out of the dashboard. After 5 wrong tries, CleanCut makes everyone wait before trying again, and the wait grows with each wrong try (up to 15 minutes). If you've forgotten the password, a small empty file clears it. Nothing else is lost.

  • Locked out after wrong tries: wait the time shown on the sign-in page, then try again.
  • Forgot it: make a new, empty file named RESET_PASSWORD (capital letters, nothing after it: no .txt) in CleanCut's settings folder. Then reload the CleanCut page and choose a new password. Your settings, word list and library are kept. Every other browser and phone is signed out and needs the new password.
    • CasaOS: open the Files app → AppData → clean-media → config → cleanmedia. Click Upload or create → New file, name it RESET_PASSWORD, and save it.
    • Unraid: the folder is /mnt/user/appdata/clean-media/cleanmedia/.
    • Docker Compose: ./config/cleanmedia/, next to your docker-compose.yml.
    • Synology / QNAP / TrueNAS: the folder you chose for /config when installing, then cleanmedia/.
    • Any server, from a terminal: docker exec clean-media touch /config/cleanmedia/RESET_PASSWORD

The VPN won't connect

What this means: a VPN (virtual private network) is a private, scrambled connection through a VPN company's server. CleanCut sends all its download traffic through it, which keeps your home address private. Until the VPN connects, nothing downloads. (Only using CleanCut to clean the movies and shows you already have? Then you don't need a VPN at all.) That's on purpose: CleanCut's download safety lock (also called a kill switch) never lets downloads use your normal home connection. Your privacy is safe the whole time.

After about two minutes, CleanCut shows the reason in red above the VPN details: on the Private connection step during first setup, and later under Settings → Connection. Find that message below.

  1. "username or password was refused": you're using OpenVPN (one of the two connection types). OpenVPN needs a special service username and password from your VPN company, which is often different from your website login. Copy them again from your VPN account, paste them in, and press Save and connect.
  2. "isn't answering over OpenVPN": you're using OpenVPN too. Copy your OpenVPN service username and password again (see step 1), or type a different country in Server country (optional), then press Save and connect.
  3. "private key isn't valid", "preshared key isn't valid", "address isn't valid", "Your VPN server isn't answering" or "no internet comes through": you're using WireGuard (the faster connection type). Its private key is a long secret code from your VPN company that ends with =. Make a new WireGuard key in your VPN account (AirVPN: Client Area → Devices; Mullvad: Account → WireGuard configuration). Then paste the Private key, the Preshared key (AirVPN only) and the Address again, and press Save and connect. The Address looks like 10.123.45.67/32. The Where to find these note under Your VPN company shows where each one is.
  4. "No VPN server matches the country": check the spelling in Server country (optional) (Netherlands, not NL), or leave it empty to use the nearest country.
  5. "This server doesn't allow VPN connections": your server hasn't given CleanCut permission to make a VPN. CleanCut needs the /dev/net/tun device and the NET_ADMIN permission. The CasaOS and Unraid templates include both. With plain Docker, add --cap-add NET_ADMIN --device /dev/net/tun. On Synology, the VPN driver has to be switched on once (insmod /lib/modules/tun.ko; the install guide's Synology section shows how, no terminal needed).
  6. Switch Connection type to the other choice (OpenVPN instead of WireGuard, or the other way round). Some networks block one of them.
  7. Restart CleanCut. It's like switching it off and on again. Nothing is lost: it picks up exactly where it left off.
    • CasaOS: on the CasaOS dashboard, right-click CleanCut's icon (or click the ⋮ dots on the icon), then click the round-arrow restart button at the bottom of the menu.
    • Unraid: Docker tab → click CleanCut's icon → Restart.
    • Synology: Container Manager → Container → select clean-media → Action → Restart.
    • TrueNAS: Apps → select clean-media → Restart.
    • Docker: in a terminal (a window where you type commands), type docker restart clean-media.

Skipped the VPN during setup? That's fine. Until a VPN is connected nothing downloads, and Home, Find something to watch and Downloads say Downloads are paused until your VPN is set up. Press Set up my VPN there to open Settings → Connection, tap your company under Your VPN company (tap Other if it isn't shown), fill in the details and press Save and connect. Changing to another VPN company later works the same way: CleanCut reconnects by itself.

Downloading without a VPN (not recommended). Under the VPN details in Settings → Connection is a small Download without a VPN link. Without a VPN, other computers in a download can see your home internet address. Only turn this off if everything you download is yours to download, such as public-domain films (films whose copyright has run out).

CleanCut explains this, then asks you to tick two boxes and type download without vpn before it turns VPN protection off. While it's off, a red box at the top of every page says so, and the download safety lock is off too. Press Turn the VPN protection back on in that box (or save your VPN details with Save and connect) to send downloads through the VPN again, with the safety lock back on. Restoring a backup also turns VPN protection back on.

Downloads are stuck at 0% or very slow

What this means: downloads come from other people's computers that share the same file at the same moment. A download is slow when few people share it, when the VPN is off, or when port forwarding isn't set up. Port forwarding opens a door in the VPN (not on your home router) so more people can connect to you, which makes downloads much faster.

  1. Check the VPN. Open Settings → Connection. A green box that says Private connection is on means it's working. Downloads pause without it.
  2. Run the check-up. Open Help and press Run check-up. If Downloader says port forwarding isn't set up, do step 3.
  3. Set up port forwarding in Settings → Connection:
    • AirVPN: on airvpn.org, go to Client Area → Ports and reserve a port. Type that number in Forwarded port (makes downloads much faster), then press Save and connect.
    • Proton VPN, PIA and some others: turn on Use port forwarding (faster downloads, set up automatically), then press Save and connect. Proton VPN needs a paid plan, and NAT-PMP (port forwarding) turned on when you make your WireGuard configuration.
    • Mullvad, NordVPN, Surfshark and some others don't offer port forwarding here. Downloads still work, more slowly.
  4. Rare or old titles may have few people sharing them. If a download on the Downloads page shows a warning, press Try a different download. Otherwise, give it a day.
  5. Add more search sites (Search sites page), so CleanCut has more copies to choose from.

What this means: CleanCut finds movies and shows through search sites (also called indexers): websites that list what can be downloaded. Prowlarr, one of the apps built into CleanCut, searches them for you. If no site is switched on, or the built-in apps are still starting, search comes back empty.

  1. Right after installing or restarting, the built-in apps need 2–5 minutes to start. Try again shortly.
  2. Open the Search sites page. At least one site must be switched On. Press Test next to each one to check it answers. No sites yet? Search the list under Add a search site and press Add next to a site you have permission to use. CleanCut doesn't add any sites for you.
  3. The VPN must be connected, because search sites are reached through it (see The VPN won't connect).
  4. Try a shorter title (Charade instead of Charade (1963) 1080p).

I added a title but it never downloads

What this means: when you add a title, CleanCut keeps looking for a good copy to download. Until it finds one, the title waits on the Downloads page under Looking for a download. It starts by itself the moment a copy turns up.

  1. Some titles aren't on any of your search sites yet. There's nothing to do: CleanCut keeps checking and starts by itself if one appears.
  2. Add another search site you have permission to use (Search sites page). Downloads that get stuck or turn out to be broken are replaced by themselves while Replace stuck or broken downloads automatically is on (Settings → Downloads).
  3. TV shows added with Only new episodes from now on wait until the next episode airs.
  4. On the Downloads page, open Still not downloading? at the bottom. It lists the usual reasons with what to do, and marks the ones it can see happening right now.

A title downloaded but isn't in Plex

What this means: Plex is the app your family watches on. It shows what's in the folders its libraries point at. A new title can be missing because it's still being cleaned, because Plex hasn't looked at the folder yet, or because a Plex library points at the wrong folder.

  1. It may still be cleaning. Check Home → Recent activity, or Being cleaned on the Downloads page.
  2. Make sure your Plex libraries point at the right folders, inside the folder you gave CleanCut as /data when you installed it (your media drive's data folder): Movies → …/media/movies, TV Shows → …/media/tv.
  3. In Plex, point at the library, click ⋯ and choose Scan Library Files.
  4. Only kid profiles can't see it? With Hide new titles from kids until they're cleaned (recommended) on (Kids & Plex), kids see a title only once it's clean. That's intentional.

A title says "Waiting for subtitles"

What this means: CleanCut finds bad words by reading the English subtitles (the written text of what's said). Bazarr, the subtitle finder built into CleanCut, looks for them online after a title downloads. Until subtitles arrive, the title waits, hidden from kids.

  1. Bazarr usually finds English subtitles within an hour. Give it time.
  2. With Speech recognition on (Settings → Listening; it starts on Last resort), CleanCut listens to the audio itself, on your own server, when no subtitles turn up. It waits first: 12 hours unless you change Wait this many hours for subtitles first. With Only listen overnight on, the listening happens between 1 and 7 am.
  3. If Speech recognition is set to Off: wait for subtitles only and no subtitles ever appear, either set it to Last resort (CleanCut then listens after the wait), or allow the title for kids yourself (Kids & Plex → Hidden from kids right now → Allow anyway).

My own movies and shows aren't being cleaned

What this means: CleanCut cleans the movies and shows you already have when it can see the folders they're in. It sees them under /media: your app store has to give CleanCut those folders, and you choose them in CleanCut.

  1. Open Settings → General and look under Your movies and shows. Tick each folder your Plex movies and shows are in.
  2. No folders listed? CleanCut can't see them yet. In CasaOS or ZimaOS, right-click CleanCut's icon (or click the ⋮ dots on it) and choose Settings. Under Volumes, add your movies folder (for example /DATA/Media/Movies) with /media/Movies as the folder inside CleanCut, and your TV folder with /media/TV. Press Save. CleanCut restarts by itself. On Unraid, Synology, TrueNAS or Docker, add the same folders with a container path that starts with /media/.
  3. A folder says "Not found right now"? The drive it's on may be unplugged, or the folder was removed from CleanCut's settings in your app store. Plug it back in, or add it again (step 2).
  4. Titles from your own folders often have no subtitle file. CleanCut then listens to the audio itself (Settings → Listening; Last resort listens straight away for your own files). With listening off, put an English .srt subtitle file next to the video, with the same name.
  5. Cleaning takes a few minutes per movie (longer on smaller computers like a Raspberry Pi), one title at a time, so a big library takes a while. Home shows what's being cleaned right now.

Good to know: CleanCut changes the files in these folders: it adds a clean audio track, and keeps the original audio inside the file as a backup track. Back up anything irreplaceable first. Shrinking oversized videos stays off for your own folders unless you switch on Also shrink videos in my own folders (Settings → Downloads).

A title says "Needs attention"

What this means: CleanCut tried to clean a title and couldn't. The Details column under Recent activity on Home says why. Find the reason below.

  • "looks damaged or incomplete" or "has no audio track": the download itself is bad. On Library, choose the title under Manage a title, press Delete, then add it again from Find something to watch. A fresh copy is downloaded.
  • "Your media drive is full": free some space (Library → Manage a title → Delete), then press Settings → System → Advanced → Re-check whole library.
  • "CleanCut isn't allowed to change this file": CleanCut runs as a user on your server, set by PUID and PGID in CleanCut's settings in your app store. They must match the owner of your media folder. The usual values are 1000/1000; on Unraid 99/100; on Synology often 1026/100. Change them, save, and CleanCut restarts.
  • Anything else (for example "took too long"): CleanCut tries again by itself later. To retry now, press Re-check whole library.

A bad word slipped through

What this means: CleanCut mutes the words it finds in the subtitles (and, when listening is on, in the audio). Subtitles are sometimes wrong or leave a word out, so now and then a word slips through. You can fix it in under a minute.

  1. On Home, open Report a word we missed. Pick the movie or episode, type about when it happens (like 1:02:15 for 1 hour, 2 minutes and 15 seconds in) and press Mute it. CleanCut then cleans that title again with the moment muted. That takes a few minutes for a movie (longer on smaller computers like a Raspberry Pi).
  2. Type the word too, and it's added to your list for every title.
  3. Is it a word CleanCut doesn't know at all? On Word list, open Want to mute a word you don't see here? Add your own words, type it and press Add. Your whole library is checked again in the background, and the word is muted wherever the subtitles (or listening) find it. Put * at the end to catch longer forms too (frick* also mutes fricking).
  4. If you often hear the start or end of a word, set How much to mute (Settings → General) to Balanced (always a word before and after) or Wide (always the whole subtitle line). New installs start on Smart, which mutes just the word when it's sure when the word is said, a word or two around it when it's less sure, and the whole subtitle line when it can't tell.
  5. No subtitle-based filter is perfect. Setting Speech recognition to Extra-safe (Settings → Listening) also listens to every title, which catches words the subtitles leave out. It's slower.

Too much is muted (dialogue cut off)

What this means: CleanCut is muting more than you'd like: either a little too much around each word, or words you don't mind hearing. Changes apply to your whole library in the background, and the original audio is always kept, so nothing is lost.

  1. Set How much to mute (Settings → General) to Precise. It mutes just the word every time it can. Smart (where new installs start) does that only when it's sure when the word is said, and mutes a little more when it's less sure. Balanced and Wide always mute more. With any choice, a subtitle line whose timing looks unreliable is muted whole, because a wider mute is better than a missed word.
  2. On Word list, check your Filter level. Strict also mutes mild words such as hell and damn; Moderate leaves them alone.
  3. To keep one particular word, pick it under Exclude words and press Exclude selected.
  4. Did you add a word of your own that you now want to hear? On Word list, open Add your own words and press the word to take it off your list.
  5. Type a line into Test a sentence (Word list) to see exactly what would be muted.

Kids see titles that aren't clean (or see nothing at all)

What this means: CleanCut puts the label Kid Safe (a tag) on every clean title in Plex that's within your age limit. Each child's Plex profile is then set to show only titles with that label. If a child sees titles that aren't clean, their profile isn't restricted yet. If they see nothing at all, no titles have the label yet.

  1. Every child's Plex profile needs the restriction. Kids & Plex shows the exact steps under How to set up your kids' Plex profiles (Allow labels: Kid Safe under Movies and TV Shows).
  2. Can't find the label setting in Plex? Plex offers label restrictions only when the account that owns the Plex server has Plex Pass (Plex's paid plan), and when the child's restriction profile is set to None.
  3. Put a PIN on your own Plex profile, or a child can switch to it.
  4. Kids see nothing at all? Check that Plex is connected (Kids & Plex). Titles get the label only once they're clean and within Kids can watch, about a minute after cleaning finishes. Wait for the first titles.
  5. Titles that were already in your library before CleanCut get the label once they've been checked. Press Settings → System → Advanced → Re-check whole library.

CleanCut can't connect to Plex

What this means: CleanCut talks to your Plex server to add labels and refresh your library. It signs in with your Plex account, then reaches the Plex server over your home network.

  1. Sign in again on Kids & Plex, using the Plex account that owns the server: press Step 1: Sign in with Plex, then Step 1: Open the Plex sign-in page and sign in on the Plex page that opens. Come back to the CleanCut tab: it notices by itself within a few seconds, or press Step 2: I've signed in. (Skipped Plex during setup? This is where to connect it.)
  2. Plex must be running and reachable. Open http://<plex-computer>:32400/web in a browser to check. If Plex says the server isn't claimed yet, sign in there once so it belongs to your account.
  3. Plex on a different computer? CleanCut must be allowed to reach it outside the VPN. In Settings → Connection, open Advanced (inside the VPN details) and make sure Home network ranges that bypass the VPN includes that computer's network, then press Save and connect. The usual home ranges are already there; 192.168.1.0/24, for example, covers every address from 192.168.1.0 to 192.168.1.255.

"The cleaning engine isn't running"

What this means: the cleaning engine is the part of CleanCut that mutes and labels titles. While it's stopped, new titles wait (hidden from kids). Nothing is lost.

  1. Restart CleanCut. It's like switching it off and on again. Nothing is lost: it picks up exactly where it left off.
    • CasaOS: on the CasaOS dashboard, right-click CleanCut's icon (or click the ⋮ dots on the icon), then click the round-arrow restart button at the bottom of the menu.
    • Unraid: Docker tab → click CleanCut's icon → Restart.
    • Synology: Container Manager → Container → select clean-media → Action → Restart.
    • TrueNAS: Apps → select clean-media → Restart.
    • Docker: in a terminal (a window where you type commands), type docker restart clean-media.
  2. If the message comes back, open Settings → System and look at System status. Note which part doesn't say Running, and send that together with CleanCut's logs (see I can't open the dashboard, step 6) with your question.

The media drive is full, or looks disconnected

What this means: your movies and shows live on your media drive: the big drive you chose for CleanCut's /data folder when installing. When it's full, nothing new can download or be cleaned. "Disconnected" means CleanCut can't see the drive at all, usually because a USB drive came unplugged or the server didn't connect it when it started.

  • Full: delete what you no longer watch (Library → Manage a title → Delete). Make sure Free up space as soon as a title is cleaned is on (Settings → Downloads): each title then takes up space only once. Shrink oversized videos in the background (same page) also saves space over time: after a title is cleaned, a video file that's much bigger than it needs to be waits in a queue and is re-saved in a more space-efficient format in the background, on your server's graphics chip if CleanCut can use one. What you see and hear stays the same. Switch it off there to stop it.
  • "Media drive looks disconnected": check that the drive is plugged in and switched on, and that your server shows it, then restart CleanCut. CleanCut never forgets your cleaned titles because of a missing drive.

What this means: when a download finishes, CleanCut normally adds it to your library with a hardlink: a second name for the same file, so it shows up in two folders without using space twice. That only works when downloads and your library are on the same drive, inside the one folder you gave CleanCut as /data. Otherwise the file is copied, which uses twice the space for a while.

  1. Use one folder for everything (for example /DATA/Media/data). Don't point /data/media or /data/torrents at different drives or shared folders.
  2. Drives formatted as exFAT or FAT32 (the way many USB drives come), and some network shares, can't make hardlinks. For media, use a drive formatted as ext4, XFS, Btrfs or ZFS (Linux formats). Formatting erases a drive, so copy your files off first.
  3. On Windows or Mac (Docker Desktop), use a drive formatted NTFS (Windows) or APFS (Mac). If downloads are still copied there, that's expected: Free up space as soon as a title is cleaned (Settings → Downloads) removes the extra copy.
  4. Restart CleanCut. It's like switching it off and on again. Nothing is lost: it picks up exactly where it left off.
    • CasaOS: on the CasaOS dashboard, right-click CleanCut's icon (or click the ⋮ dots on the icon), then click the round-arrow restart button at the bottom of the menu.
    • Unraid: Docker tab → click CleanCut's icon → Restart.
    • Synology: Container Manager → Container → select clean-media → Action → Restart.
    • TrueNAS: Apps → select clean-media → Restart.
    • Docker: in a terminal (a window where you type commands), type docker restart clean-media.

Using a graphics card to listen faster

What this means: listening (speech recognition) is how CleanCut finds words in titles that have no subtitles. It runs on your server's processor. An NVIDIA graphics card makes it much faster, but only once your server lets CleanCut's container (the sealed box CleanCut runs in) use the card. Everything else (Intel or AMD graphics, Raspberry Pi, Mac) listens on the processor, with nothing to set up.

  1. Install the NVIDIA driver on the server, and the NVIDIA Container Toolkit (the piece that lets containers use the card). Unraid: the Nvidia Driver plugin; TrueNAS: Apps → Settings → Install NVIDIA Drivers.
  2. Give CleanCut the card:
    • Unraid: edit the container, turn on Advanced View, add --runtime=nvidia to Extra Parameters.
    • Docker Compose / CasaOS / TrueNAS: add gpus: all under the clean-media service.
    • Docker: add --gpus all to docker run.
  3. Restart CleanCut. Settings → Listening shows the card's name. The first time, it downloads about 1.5 GB of helper files for it.

The free trial is used up, or my license key isn't accepted

What this means: the free trial cleans 3 movies and 10 TV episodes with every feature. They're counted separately, so cleaning a movie never uses up an episode, and the Try it now movie doesn't count at all. Once the 3 trial movies (or 10 trial episodes) are used up, new ones wait, hidden from kids, until you add a license key. A license is a one-time purchase with free updates for life.

  1. Titles cleaned during the trial stay clean. Settings → Account → License shows how many trial movies and episodes are left.
  2. To buy one, open Settings → Account → License and press Buy a license. Your key appears on the thank-you page and arrives by email (check your spam folder too).
  3. Paste the whole key into License key under Settings → Account → License, then press Activate. It's one long line; spaces or line breaks are fine. Titles that were waiting start being cleaned right away, a few minutes per movie (longer on smaller computers like a Raspberry Pi).
  4. Lost the key? Under Settings → Account → License, use Have it emailed to you again, or reply to the email your key came in.
  5. Two editions. CleanCut Cleaner cleans the movies and shows you already have. CleanCut Suite also finds and downloads new ones. Keys bought before there were two editions are Suite keys. With a Cleaner key, Find something to watch, Downloads, Requests and Search sites aren't shown, and CleanCut needs no VPN.
  6. Upgrading from Cleaner to Suite. Press Upgrade to Suite under Settings → Account → License (or Settings → General), paste your Cleaner key on the shop page and pay the difference. Your Suite key is emailed to the address you bought the Cleaner with. Paste it under Settings → Account → License and press Activate, then choose Also find and download new ones under Settings → General. If you installed with the Cleaner's setup file, finding and downloading needs the full install file (see the install guide), which adds what the VPN needs.

Backing up, restoring, or moving to a new server

What this means: a backup is one file with everything CleanCut needs to carry on: your settings, word list, history, VPN and Plex details, license, and your movie and show lists. Your movies and shows themselves aren't in it; they stay on your media drive. Unless you change it, CleanCut makes a backup by itself every week and keeps the newest 4.

  1. To change how often, how many to keep, or where they're kept, open Settings → System and look under Backups. If your media drive is a separate drive, choose Your media drive under Where to keep them: if the drive with CleanCut's settings ever fails, the backups are safe there.
  2. To make one right now, press Back up now. To keep a copy somewhere else too (a USB stick or cloud storage), press Download next to it under Saved backups. Keep it private: it contains your VPN keys.
  3. To go back to a backup, press Restore next to it, then Restore this backup. CleanCut restarts and is back in about a minute. Sign in with the parent password you used when that backup was made.
  4. Moving to a new server, or reinstalling: install CleanCut, and on the first setup step open Moving from another server? Restore a backup. Backups kept on your media drive are listed there; otherwise upload a backup file you downloaded.
  5. Automatic backups aren't working: Settings → System says why under Backups. If your media drive is unplugged or full, plug it back in or free up some space; CleanCut tries again every hour. Or choose CleanCut's settings folder under Where to keep them.

The server feels slow while cleaning

What this means: cleaning, listening and shrinking use some of your server's power. On a small server, that can make Plex or other apps feel slow while they run. These settings keep CleanCut out of the way.

  1. Keep Pause cleaning while someone is watching Plex on (Settings → Downloads).
  2. On Settings → Listening, set Listening quality to Fast, or turn on Only listen overnight (1–7 am) so the server stays snappy.
  3. Shrink oversized videos in the background (Settings → Downloads) pauses while someone watches Plex too. Turn it off if the server still feels slow.
  4. Cleaning copies the picture as it is, without re-encoding it (re-making the video, which is slow), so the work is mostly reading and writing the drive. It still takes a few minutes per movie (longer on smaller computers like a Raspberry Pi), and finishes by itself.

No sound, wrong sound or out-of-sync sound on the TV

What this means: every cleaned title has a clean audio track called Clean (Family Safe), plus the original as a backup track. Plex picks which track plays, and some TVs and sound bars can't play every audio format.

  1. In the Plex player, open the audio menu and make sure Clean (Family Safe) is selected.
  2. Older TVs or sound bars: set Clean audio format to Dolby Digital 5.1 (Settings → General). For phones and tablets, Stereo AAC plays everywhere. Titles are re-cleaned in the background to match.
  3. If only one title is out of sync, the download itself is usually the problem. Delete it (Library → Manage a title → Delete) and add it again.

Subtitles show up by themselves on the TV

What this means: CleanCut marks its clean subtitles as the main (default) subtitle track, so some Plex apps show them without being asked.

In Plex, open Settings → Languages and set Subtitle mode to Manually selected. To see subtitles when you want them, pick English (Clean) in the player.

"The built-in apps are still starting" for a long time

What this means: inside CleanCut run well-known apps that do the behind-the-scenes work: Sonarr (TV shows), Radarr (movies), Prowlarr (search sites), qBittorrent (downloads) and Bazarr (subtitles). CleanCut starts them and links them together for you. Until that's done, searching and downloading wait.

  1. The first start takes up to 5 minutes. Later starts take about a minute.
  2. Open Settings → System and look at System status. Every part should say Running. The downloader and the apps for TV shows, movies, search sites and subtitles wait for the VPN, so connect the VPN first.
  3. Press Settings → System → Advanced → Re-connect apps.
  4. Restart CleanCut. It's like switching it off and on again. Nothing is lost: it picks up exactly where it left off.
    • CasaOS: on the CasaOS dashboard, right-click CleanCut's icon (or click the ⋮ dots on the icon), then click the round-arrow restart button at the bottom of the menu.
    • Unraid: Docker tab → click CleanCut's icon → Restart.
    • Synology: Container Manager → Container → select clean-media → Action → Restart.
    • TrueNAS: Apps → select clean-media → Restart.
    • Docker: in a terminal (a window where you type commands), type docker restart clean-media.

Using CleanCut away from home, and phone apps like Helmarr and nzb360

What this means: at home, your phone reaches CleanCut over your Wi-Fi. Away from home it can't, because your home network is private. The free Tailscale app fixes that safely: it makes a private, encrypted link between your own devices, so your phone reaches your server from anywhere, as if you were home. No router changes, and nothing is opened to the internet.

Tailscale is a different thing from the VPN CleanCut uses for downloads. The download VPN hides your downloads; Tailscale only connects your own phone and server to each other. They work side by side, and your downloads still only ever go through the download VPN. Tailscale's Personal plan is free for personal (non-business) use.

Part 1: put Tailscale on your server (once)

  1. Make a free account at tailscale.com (Get Started). You can sign up with an account you already have, such as Google, Microsoft or Apple.
  2. Install Tailscale on the server and sign in with that account:
    • CasaOS: CasaOS's own App Store doesn't have Tailscale, and the community version runs it boxed in, where it can't reach CleanCut. Put it on the server itself instead: open a terminal the same way you did to install CasaOS, type curl -fsSL https://tailscale.com/install.sh | sh, press Enter, then type sudo tailscale up and open the link it shows to sign in.
    • Unraid, Synology, TrueNAS: Tailscale is in your server's app store too (Unraid: Apps tab; Synology: Package Center; TrueNAS: Apps). Install it and follow its sign-in steps. Tailscale's own guide for each is at tailscale.com/kb/1307/nas.
    • Windows or Mac: install Tailscale from tailscale.com/download on the computer that runs CleanCut, and sign in.
    • Raspberry Pi or other Linux: in a terminal, type curl -fsSL https://tailscale.com/install.sh | sh, then sudo tailscale up, and open the link it shows to sign in.
  3. Recommended: stop Tailscale from signing your server out every few months. Go to login.tailscale.com/admin/machines, click the ⋯ menu at the end of your server's row, and choose Disable key expiry.

Part 2: put Tailscale on your phone

  1. Install Tailscale from the App Store (iPhone) or Google Play (Android).
  2. Open it and sign in with the same account you used for the server. When your phone asks to add a VPN configuration, allow it: that's how Tailscale makes its private link.
  3. Keep Tailscale switched on whenever you want to reach home. Phones run one VPN app at a time, so if you use another VPN app on your phone, turn it off while you use Tailscale.

Part 3: open CleanCut from anywhere

  1. Find your server's Tailscale name. Your devices are listed by name in the Tailscale app on your phone and at login.tailscale.com/admin/machines. The server is one of them, for example casaos.
  2. In your phone's browser, go to http://<server's Tailscale name>:8585, for example http://casaos:8585 (use your app store's port if you changed it). Sign in with your parent password.
  3. Name won't open? Use the server's Tailscale address instead: four numbers that start with 100., listed with the server in the same places (for example http://100.101.102.103:8585).
  4. Tip: add the page to your home screen so it opens like an app (iPhone: Share → Add to Home Screen; Android: ⋮ → Add to Home screen).
  5. Don't open ports on your router (that means making your server reachable by anyone on the internet). With Tailscale it's not needed, and it's not recommended.

Part 4: phone apps such as Helmarr and nzb360 (optional)

Behind CleanCut's simple pages run Sonarr (TV shows), Radarr (movies), Prowlarr (search sites), qBittorrent (downloads) and Bazarr (subtitles). They're powerful but hard to set up by hand, so CleanCut sets them up for you and keeps them out of sight. If you'd like a phone app for them, Helmarr (iPhone and iPad, iOS 26 or later) and nzb360 (Android) can talk to them directly. Both are free to download, with paid upgrades. This is optional: CleanCut's own pages already work in your phone's browser. Everything added through a phone app still downloads through your VPN and is cleaned before kids can see it.

  1. Turn it on in CleanCut. Open the page list (on a phone, tap the menu button at the top left), then under Setup choose Settings. Open the Connection tab (swipe the row of tabs if you don't see it), scroll down to Phone apps and request services, and switch on Allow phone apps and request services.
  2. See what to copy. CleanCut now shows the Host (your server's address) and Port to use, and a table with each service's Path and API key (a long password that lets an app talk to another app; keep it private). qBittorrent uses the username admin and the password shown in the table instead.
  3. Add each service in your phone app, choosing the matching type (Sonarr, Radarr, Prowlarr, qBittorrent, Bazarr):
    • If the app has one address box, type it all together: http://<host>:<port><path>, for example http://192.168.1.50:8585/sonarr.
    • If it has separate boxes, type the host and the port in theirs, and the path (for example /sonarr) in the box called URL base or path.
    • Paste that service's API key (or, for qBittorrent, the username and password). Leave SSL or HTTPS off.
  4. Helmarr: CleanCut's Settings → Connection page has these steps with your own details filled in, under Step by step: Helmarr.
  5. nzb360: in nzb360's settings, add Sonarr, Radarr, Prowlarr, Bazarr and qBittorrent the same way: the address including the path, and the API key.
  6. Away from home: with Tailscale on, use the server's Tailscale name as the host (for example http://casaos:8585/radarr). If you use the Tailscale name everywhere, the same setup works at home and away. Helmarr can also keep a separate home address and away address for each service.
  7. Seerr, a request service where family members ask for titles, connects the same way: see Step by step: Seerr (family requests) on the same page.

Use phone apps to add, search and check on titles. Avoid changing their settings (quality profiles, folders, download clients): CleanCut set those up, and changes there can break its automatic setup.

If a phone app can't connect:

  1. It says "Phone app access is off": the switch in step 1 is off. Turn it on, wait a few seconds, and try again.
  2. Check the path is included (/sonarr, /radarr...), the port is the one CleanCut shows, and SSL is off.
  3. Away from home, check Tailscale is switched on on your phone.

Guides

CleanCut Suite 1.3.1 · by Harrelson Products and Services Install · From your phone · Help · Lost your key? · Refunds · License · Terms · Privacy CleanCut Suite is not affiliated with or endorsed by Plex Inc.