Install CleanCut Suite

This guide takes you from nothing to your first clean movie. You don't need any experience with Linux, CasaOS, Docker or home servers. Start at the top and follow along: every step says what you will see and where to click, and every technical word is explained the first time it shows up.

How long it takes: on a server that already runs CasaOS or ZimaOS and Plex, about ten minutes from the app store. Starting with a computer that has nothing on it yet? Plan an evening: most of that is waiting while things download.

On this page

1. Before you start: a quick checklist, what you need in plain words, and how to get CasaOS or ZimaOS if your server doesn't have one yet
2. Find your server's address
3. Install on CasaOS or ZimaOS: add the CleanCut store (easiest), or paste the app file
4. Clean the movies and shows you already have
5. Your first 10 minutes: the setup guide
6. Add your movies and shows to Plex
7. Use it from your phone or away from home
8. Other systems: Unraid, Synology, TrueNAS, QNAP, Raspberry Pi or any Linux, Mac, or Windows (Windows in early access), and the CleanCut Cleaner file
9. For experienced users, graphics cards, updating and help

Before you start

Do you have these?

• A computer that stays on at home, such as a mini-PC, a Raspberry Pi 5 or a NAS (a storage box for your home network).
• A big drive for your movies and shows.
• Plex, the free app your family watches on. Locking kid profiles to clean titles needs Plex Pass, Plex's paid plan.
• CasaOS or ZimaOS on that computer (or Unraid, Synology, TrueNAS or QNAP). No idea what that means? Start here.

Optional: a VPN subscription, only if you'd like CleanCut to find and download new titles too (see below).

What CleanCut is, in one minute

CleanCut is one app that runs on a computer in your home. It's a profanity filter for Plex: it mutes the swear words in the movies and shows on your Plex, stars them out in the subtitles, and labels clean titles Kid Safe, so your kids' Plex profiles only show titles that are clean and right for their age. You manage it from one page, the dashboard, in your web browser.

How it finds the words: it reads the subtitles to see when each word is said. When a title has no subtitles, or the subtitles leave a word out, it can listen to the audio itself, right on your server. Nothing is uploaded anywhere. The original audio stays inside each file as a backup track, so you can always switch back.

Finding new titles is optional. If you'd like, CleanCut can also find and download new movies and shows from search sites you add yourself. It comes with no search sites switched on. For this part it uses well-known free tools that are built in, set up and connected for you, so you never need to open them:

• Radarr finds movies and Sonarr finds TV shows.
• Prowlarr keeps the list of search sites you added.
• qBittorrent does the downloading.
• Bazarr fetches subtitles (CleanCut uses these for cleaning, for the movies you already have too).
• An optional VPN with a kill switch keeps your home internet address private while CleanCut downloads (explained below).

What you need, in plain words

• A server. A server is a computer that stays on at home, day and night. It doesn't need a screen once it's set up. A small, quiet mini-PC works well. The minimum is a Raspberry Pi 5 (4 GB) or any 64-bit Intel or AMD computer from the last 8 years or so, with 4 GB of RAM (RAM is the computer's working memory). Cleaning only happens while it's switched on and awake.
• A big drive for your movies. Movies and shows take a lot of space, so they should go on a large hard drive or SSD (a fast drive with no moving parts), not the small drive the system runs on. If you can, keep CleanCut's settings folder on an SSD: it makes CleanCut quicker.
• CasaOS or ZimaOS (recommended). Both are free, app-store-style home screens for that computer, made by the same company. You open them in a web browser from your own laptop or phone, and they let you install apps with a few clicks. Unraid, Synology, TrueNAS and QNAP have their own app screens and work too.
• Docker (CasaOS and ZimaOS handle it for you). Docker is the free engine that runs server apps. Each app lives in its own sealed box, called a container, with everything it needs inside. CleanCut is one container.

• Plex. Plex is what your family watches on: there are Plex apps for TVs, streaming sticks, phones and tablets. It has two parts: Plex Media Server, which runs on your server, and the Plex app on each screen. Install Plex Media Server before you start the setup guide (on CasaOS and ZimaOS it's in the App Store, see the steps below), open it once and sign in with a free Plex account. Not on CasaOS or ZimaOS? Download Plex Media Server from plex.tv, or install it from your NAS's app screen. CleanCut labels each clean title Kid Safe, and your kids' Plex profiles can be set to show only titles with that label.

  Two things to know about Plex's paid plans: the kid-profile setting uses Plex's label restrictions, which Plex offers only when the account that owns your Plex server has Plex Pass. And watching your movies away from home needs Plex Pass or Plex's Remote Watch Pass. Watching at home is free, and CleanCut's cleaning works either way.

• A VPN subscription (optional). You only need this if CleanCut will download new titles. A VPN (virtual private network) is a paid service from another company that sends internet traffic through a private, encrypted tunnel, so other computers see the VPN company's address instead of your home's. It's recommended for downloading because it keeps your family's home address private. CleanCut sends all its downloading through it, and its kill switch stops downloading if the VPN ever drops. Your VPN company must support WireGuard or OpenVPN (the two standard ways a VPN connects; most large VPN companies offer both).

• About 3 GB of internet download for CleanCut itself.

Don't have CasaOS or ZimaOS yet? Start here

Some small home servers (such as ZimaBoard and ZimaCube) come with CasaOS or ZimaOS already installed. If yours did, skip this part and go to Find your server's address.

Otherwise, your server first needs Linux. Linux is a free operating system: the system that starts the computer, like Windows on a PC or macOS on a Mac. Most home servers use it. You set it up once, using your laptop and a memory card or USB stick. This erases whatever is on the server's drive (or card), so use a computer you don't need anything from. If you can, connect the server to your router with a network cable: it's more reliable than Wi-Fi for a server.

1. Put Linux on the server. Pick the one that matches your server:
   • Mini-PC, the easiest way: ZimaOS. ZimaOS comes from the company that makes CasaOS and has an App Store built in, so you won't need to type any commands. It has a free version. Follow ZimaOS's own guide at zimaspace.com: you put ZimaOS on a USB stick using your laptop, start the mini-PC from the stick (the guide shows how), and it installs itself. When it's finished, it shows the server's address. Open that address on your laptop, follow ZimaOS's short first-time setup, and skip ahead to Install on CasaOS or ZimaOS.
   • Raspberry Pi. On your laptop, install the free Raspberry Pi Imager from raspberrypi.com/software and put the Pi's microSD card in your laptop. In Imager, choose your Pi, then Raspberry Pi OS Lite (64-bit) (if it's not in the first list, look in the other Raspberry Pi OS versions), then your microSD card. When Imager offers to customise the system, type a username and password, and turn on Enable SSH (a way to type commands on the Pi from your laptop). Write the username and password down. Then press Write and confirm; Imager warns that the card will be erased, which is expected. When it's done, put the card in the Pi and switch it on.
   • Mini-PC with Ubuntu Server (a free, widely used Linux). Follow Ubuntu's guide at ubuntu.com/tutorials/install-ubuntu-server. You put the installer on a USB stick, start the mini-PC from the stick, and answer a few questions. When it asks you to choose a username and password, write them down. If it offers to install the OpenSSH server, turn that on: it lets you type commands from your laptop later.
2. Raspberry Pi or Ubuntu: add CasaOS. First open the terminal, a window where you type commands instead of clicking. The easiest way: plug a screen and keyboard into the server, wait for it to start, and sign in with your username and password. The black screen with a blinking cursor is the terminal. (If you turned on SSH, you can use your laptop instead: open PowerShell on Windows or Terminal on Mac, type ssh yourname@<server address> with your own username, press Enter, type yes if it asks whether to continue connecting, then type your password.)

3. Type this exactly, then press Enter. It's CasaOS's official installer:

   curl -fsSL https://get.casaos.io | sudo bash
   

4. When it asks for your password, type it and press Enter. Nothing appears on screen while you type; that's normal. The install takes a few minutes.

5. When it finishes, it shows an address and the line Open your browser and visit the above address. Write the address down, then open it on your laptop or phone. The first time, CasaOS shows Welcome to CasaOS: press Go, choose a Username and Password, and press Create. You can unplug the screen and keyboard from the server now.

Find your server's address

Every device on your home network has an address, called an IP address. It's four numbers with dots between them, such as 192.168.1.50. You reach CleanCut by typing that address into your browser, followed by :8585. The 8585 is the port: a door number on the server that leads to CleanCut.

So if your server's address is 192.168.1.50, CleanCut is at http://192.168.1.50:8585. Always type http://, not https://.

Ways to find the address, easiest first:

1. By name. Try typing http://casaos.local into your browser first. Servers that came with CasaOS (such as a ZimaBoard) usually answer to that name. If CasaOS opens, you can use the name instead of the numbers: CleanCut is then at http://casaos.local:8585. If nothing opens, use one of the ways below.
2. From the CasaOS or ZimaOS installer. If you installed it yourself, the address is the one it showed when it finished (for CasaOS, the one above Open your browser and visit the above address.).
3. From your router. Your router is the box from your internet company that makes your Wi-Fi. Its phone app or settings page has a list of connected devices (often called Devices, Clients or Attached devices). Find your server in that list and note its IP address.
4. Already have CasaOS or ZimaOS open? Look at the address bar at the top of your browser. The part after http://, up to the next / or :, is your server's address: numbers such as 192.168.1.50, or a name such as casaos.local. Either works. Put :8585 after it for CleanCut.

Tip: in your router's settings, look for address reservation (sometimes called DHCP reservation or static IP) and reserve your server's address. That way it never changes, and your bookmarks keep working after a power cut.

Install on CasaOS or ZimaOS (recommended for beginners)

There are two ways. Option A is the easiest: you add the CleanCut store to your App Store once, then install CleanCut like any other app, and updates appear there too. Option B pastes the app file by hand, and works on every version.

Option A: add the CleanCut store, then install

On CasaOS:

1. On your laptop or phone, open CasaOS in your browser and sign in.
2. Open the App Store. Its icon is on the CasaOS home screen.
3. At the top right of the App Store, click More apps (the button with a +). If you've added another store before, that button shows a number of apps instead, such as 150 apps: click it, then choose More apps.

4. A box appears. Paste this address into it, exactly, and click Add:

   https://github.com/LumbleHamb/cleancut-store/archive/refs/heads/main.zip
   

5. Wait a few seconds while CasaOS loads the store. Then type CleanCut into Search an app... and click CleanCut.

6. Click Install. Before you confirm, check the folders under Volumes (see Check the folders below).

On ZimaOS:

1. Open ZimaOS in your browser, sign in, and open the App Store.

2. Choose Add source. Paste this address, exactly, and confirm:

   https://cdn.jsdelivr.net/gh/LumbleHamb/cleancut-store@gh-pages/store.json
   

3. If CleanCut doesn't show up straight away, refresh the page. Then search for CleanCut, click it and click Install. Before you confirm, check the folders (below).

ZimaOS needs the store.json address; CasaOS needs the .zip address. If one is refused, check you used the right one for your system, and that nothing extra was pasted after it.

When the install is done, a CleanCut icon appears on the home screen. Carry on with After installing.

Option B: paste the app file (Custom Install)

1. Open CasaOS (or ZimaOS) in your browser, sign in, and open the App Store.
2. Click Custom Install in the top right corner. An empty app form opens. (Don't see it? On the CasaOS home screen, click the + next to Apps and choose Install a customized app.)
3. Click the Import icon in the top right corner of that form. A window opens with two tabs, Docker Compose and Docker CLI. Stay on Docker Compose.
4. Give it the CleanCut app file. Either way works:
   • Copy and paste: open casaos-app.yaml in a new browser tab. Select everything (Ctrl+A on Windows, Cmd+A on Mac), copy it (Ctrl+C or Cmd+C), go back to CasaOS and paste it into the big text box (Ctrl+V or Cmd+V).
   • Upload the file: if your browser saves the file instead of showing it, click Drop your Docker Compose here or click to upload and pick the file from your Downloads folder.
5. Click Submit. The app form is filled in for you.
6. Check the folders (below), then click Install.

Check the folders

Scroll down to Volumes. Each row links a folder on your server (the Host box) to a folder inside CleanCut (the Container box).

• The row whose Container box says /config is CleanCut's settings. Leave it as it is.
• The row whose Container box says /media (if there is one) is your server's media folder, /DATA/Media. That's where CleanCut looks for the movies and shows you already have. Leave it as it is; the next part explains how to add folders from other drives.
• The row whose Container box says /data is CleanCut's own working folder: new titles it finds go there, and its backups can too. It starts as /DATA/Media/data, which is on the drive CasaOS itself runs on. If your server has one large drive, leave it. If your movies should live on a separate big drive, change the Host box to a folder on that drive. To find the right folder:
  1. Open CasaOS in a second browser tab and click the Files app.
  2. Your drives are listed on the left, under Location. Click your big drive.
  3. Click Upload or create, choose New folder, and name it data.
  4. Right-click the new data folder and choose Copy path.
  5. Go back to the first tab, select everything in the Host box, and paste (Ctrl+V on Windows, Cmd+V on Mac).
• Leave everything else in the form as it is.

After installing

1. CleanCut is about 3 GB, so the install can take a while on a slower connection. When it's done, click the CleanCut icon on the home screen. The dashboard opens in a new browser tab at http://<your-server>:8585. Bookmark it. If the page doesn't load, wait two minutes and try again: everything starts up in the background the first time.
2. Install Plex too (skip this if you already have Plex). Open the App Store, search for Plex, and click Install. Then click the Plex icon, sign in with your free Plex account, and follow Plex's own short setup.
3. Carry on with the setup guide below.

CleanCut's settings live in /DATA/AppData/clean-media/config. To change a folder or any other setting later, hover over the CleanCut icon on the home screen, click the three dots, and choose Settings.

Already installed CleanCut the older way, with Custom Install? You don't need to change anything: keep using it, and your settings stay where they are.

Clean the movies and shows you already have

Most families start here. CleanCut can clean the movies and shows already on your Plex, so you don't need to download anything.

Where CleanCut looks. Inside CleanCut, your existing movie and TV folders appear under /media. Installed from the CleanCut store on CasaOS or ZimaOS, /media is your server's /DATA/Media folder, so a folder such as /DATA/Media/Movies shows up in CleanCut as /media/Movies. You pick the ones to clean in the setup guide, or later in Settings.

Your movies are on another drive? Give CleanCut that folder too, once:

1. Open the Files app in CasaOS or ZimaOS, find the folder your Plex movies are in, right-click it and choose Copy path.
2. Hover over the CleanCut icon on the home screen, click the three dots, and choose Settings.
3. Under Volumes, click + (add). In the new row, paste the path into the Host box. In the Container box, type /media/ followed by a short name, for example /media/movies-2.
4. Click Save. CleanCut restarts by itself, and the folder appears in its list.

Do the same for a TV folder if it's somewhere else too.

Before CleanCut cleans them, please read this. CleanCut rewrites these files in place to add the clean audio track. The original audio stays inside each file as a backup track, so you can always switch back. Even so, as with anything that changes your files, back up anything irreplaceable first (home videos, for example), or copy a few titles to a test folder and try those first.

Shrinking stays off. CleanCut can shrink very large videos to save space. For folders you already had, that's switched off. If you want it, it's a separate switch in Settings.

Your first 10 minutes: the setup guide

The first time you open CleanCut, a setup guide walks you through everything. A bar at the top shows where you are. You can go Back at any time, and everything you choose can be changed later.

Not ready for a step? Several steps have a small Skip for now button under Next. CleanCut explains what won't work yet and asks once more (Yes, skip for now). Afterwards, Home lists anything you skipped under Finish setup, with a button to the right place, until it's done.

First: create your parent password

You'll see Create your parent password. This dashboard decides what your kids can hear and see, so it's always protected. Type a password of at least 8 characters into Password and Type it again, then press Create password. Pick something your kids won't guess, and keep it somewhere safe.

What would you like CleanCut to do?

This is the first choice, and it decides which steps come next:

• Clean the movies and shows already on my Plex. The simplest setup. CleanCut skips the VPN and search-site steps. Pick this if you're not sure: you can switch on finding new titles later in Settings.
• Also find and download new ones. Adds the optional VPN step and the search-sites step.

Your movies and shows

What you'll see: the folders CleanCut can see under /media (see Clean the movies and shows you already have).

What to do: tick the folders your Plex uses for movies and TV shows, and read the note about backing up. Don't see your folder? Add it as a volume first (the steps are in that section), then come back. You can also add folders later in Settings.

Media drive

What you'll see: Is this your media drive?, with the folder CleanCut keeps its own files in (its /data folder) and how much free space it has.

What to do: if the free space looks like your big drive, tick the box to confirm and press Next. If CleanCut warns that the folder is on the same drive as your system, it's usually the wrong place. Open It's not the right drive. How do I change it? for the fix (on CasaOS and ZimaOS, it's the /data row under Volumes in the app's Settings, as described above).

Moving from another server, or reinstalling? Open Moving from another server? Restore a backup. Backups CleanCut kept on your media drive are listed there; press Restore next to one. Otherwise, upload a CleanCut backup file you downloaded.

Private connection (optional, only if CleanCut downloads)

What you'll see: Connect your VPN. This step only appears if you chose Also find and download new ones. A VPN is recommended for downloading because it keeps your family's home internet address private. You can skip it.

What to do:

1. Under Your VPN company, tap your company. Not there? Tap Other to see the rest.
2. Choose the Connection type: WireGuard (faster) or OpenVPN. CleanCut picks the usual one for your company.

3. Fill in the boxes with details from your VPN company's website. For several companies, CleanCut shows Where to find these right under the list. In short:

   VPN company	Where to find the details
   AirVPN	airvpn.org → Client Area → Config Generator → choose WireGuard, then copy the Private key, Preshared key and Address. Optionally reserve a port under Client Area → Ports and type it into Forwarded port.
   Proton VPN	account.protonvpn.com → Downloads → WireGuard configuration, then copy the PrivateKey and Address from the configuration it gives you.
   Private Internet Access	Your PIA username (it starts with p) and password.
   Mullvad	mullvad.net → Account → WireGuard configuration, then copy the PrivateKey and Address.
   Others	Sign in on the company's website and look for WireGuard configuration or manual setup. For OpenVPN, many companies give you a separate service username and password, which is often not the one you log in to their website with.

   A WireGuard configuration is a small text file. You can open it in Notepad (Windows) or TextEdit (Mac). The value after PrivateKey = goes in Private key, and the value after Address = goes in Address (it looks like 10.x.x.x/32). If the Address line has two values separated by a comma, copy only the first one, the one that starts with 10.. For AirVPN, the value after PresharedKey = goes in Preshared key. Copy them exactly, including any = at the end.

4. Server country (optional): leave it empty to use the closest country, which is usually the fastest.

5. Press Save and connect. Within about a minute you'll see a green message, Private connection is on, and the button at the bottom changes to Next.

If it takes longer than two minutes, CleanCut shows the reason and how to fix it. The troubleshooting guide has more under The VPN won't connect.

Don't have your VPN details yet? Press Skip for now, then Yes, skip for now. Cleaning the movies you already have works without it. Fill in your VPN details later in Settings → Connection whenever you're ready.

Getting ready (only if CleanCut downloads)

What you'll see: Getting everything ready, with a checklist of the built-in apps starting up and being connected to each other. This is the part that normally takes people hours. Here it takes a minute or two.

What to do: wait for Everything is connected and ready., then press Next.

Search sites (only if CleanCut downloads)

What you'll see: Choose where to search. Search sites (also called indexers) are the websites CleanCut looks through to find new titles. CleanCut comes with none switched on.

What to do: add the sites you have permission to use, one at a time. The list shows every public site the built-in Prowlarr supports, from A to Z, with a search box at the top. Nothing in it is picked for you. Each site you add has a Test button and an On switch. Then press Next. Not sure yet? Press Skip for now (then Yes, skip for now). You can add sites whenever you like in Settings → Search sites.

Plex and kids

What you'll see: Connect Plex and set an age limit.

What to do:

1. Make sure Plex Media Server is running and you have signed in to it once. This is also a good moment to check your movie and TV folders are in Plex.
2. Signing in takes two numbered steps, each with a big button. Under Step 1 · Sign in to Plex, press Step 1: Sign in with Plex, then Step 1: Open the Plex sign-in page. A Plex page opens in a new tab. Sign in there.
3. Go back to the CleanCut tab. CleanCut notices by itself within a few seconds, or press Step 2: I've signed in. You'll see Connected to your Plex server with your server's name.
4. Under Kids can watch, choose an age limit, for example Up to PG and TV-PG. Titles rated above it stay hidden from kid profiles, even after cleaning, because muting fixes language, not other scenes.
5. Open How to set up your kids' Plex profiles and follow it once for each child. No Plex profile for your child yet? In Plex, open Settings → Plex Home and add a user for each child (Plex calls it a managed user: a profile for someone without their own Plex account). The key steps: put a PIN on your own Plex profile. Then, in each child's Restrictions, set the Restriction Profile to None and save. Plex shows the label boxes only then, and only when your Plex account has Plex Pass (Plex's paid plan). Then, under both Movies and TV Shows, set Allow labels to Kid Safe. From then on, your children only see titles CleanCut has marked as clean and within your age limit.
6. Press Next.

Not ready yet? Press Skip for now under Next, then Yes, skip for now. CleanCut still cleans without Plex, but it can't keep titles that aren't clean yet away from your kids' Plex profiles until Plex is connected. Connect it later on the Kids & Plex page.

Words

What you'll see: What should be muted?, with four filter levels:

• Lite: strong profanity and slurs.
• Moderate (recommended): everything in Lite, plus sexual content and drug references.
• Strict: everything in Moderate, plus mild language and religious expressions.
• Custom: choose individual categories.

What to do: pick one (Moderate suits most families) and press Next. You can look at the exact words with View the words in this filter, and change everything later on the Word list page. Thinking of a word that isn't there? Open Want to mute a word you don't see here? Add your own words, type it and press Add (before you press Next).

Done

What you'll see: You're all set (or Setup is done for now, if you skipped a step).

What to do: if you chose Also find and download new ones and your VPN is set up (or you chose to go without one), press Try it now with Charade (1963) to see the whole thing work. It's a free, public-domain classic, fetched from the Internet Archive (a free online library of public-domain films). It's cleaned in a few minutes once it has arrived (longer on smaller computers like a Raspberry Pi), and appears in Plex. It doesn't count toward your free trial. If you chose Clean the movies and shows already on my Plex, you won't see this button: CleanCut starts cleaning the movies and shows in the folders you picked, one at a time, and you can follow along on Home and in your Library. Then press Go to my dashboard. If you skipped a step, it's listed here under Still to finish.

After setup

• Skipped something? Home shows Finish setup with what's left, why it matters and a button to the right place. It disappears once everything is done.
• Watch in the Plex app on your TV, phone or tablet. Each title's page in CleanCut shows what was muted.
• If CleanCut downloads: add titles on Find something to watch and follow them on Downloads. Kids can ask for titles on their own page; you approve them under Requests.
• Sharing: while something downloads, the downloader also shares pieces of it with other people (that's how this kind of download works). CleanCut stops that as soon as each download finishes. If you'd rather it kept sharing for a while, switch on Keep sharing after a download finishes in Settings → Downloads. It's off unless you switch it on.
• Free trial: 3 movies and 10 TV episodes are cleaned with every feature. They're counted separately, so cleaning a movie never uses up an episode. To keep going, buy a one-time license key at shop.harrelsons.org/cleancut. Then go to Settings → Account, paste the key into License key and press Activate.
• Backups are made by themselves every week. Settings → System → Backups lists them, and lets you make one now, download one, or keep them on your media drive instead.
• If anything looks wrong, open Help and press Run check-up. It tests everything in one go and links each problem to its fix.

Add your movies and shows to Plex

Cleaning the movies you already have? Your Plex libraries already point at those folders, so there's nothing to change. CleanCut tells Plex when a title has been cleaned.

New titles CleanCut finds go into two folders on your media drive, which CleanCut creates within a minute of you confirming the drive in the setup guide:

• Movies → <your /data folder>/media/movies
• TV Shows → <your /data folder>/media/tv

Tell Plex about them once:

1. Open Plex (on CasaOS and ZimaOS, click the Plex icon; anywhere else, go to http://<your-server>:32400/web).
2. Click Settings (the wrench icon at the top right). Under Manage, choose Libraries, then Add Library.
3. Choose Movies and press Next.
4. Press Browse for Media Folder, go to the movies folder, select it, and press Add. Then press Add Library.
5. Do the same again, choosing TV Shows and the tv folder.

On CasaOS with Plex from the CasaOS App Store, and CleanCut's /data folder left at /DATA/Media/data, the folders appear in Plex as /Media/data/media/movies and /Media/data/media/tv. If you moved CleanCut's /data folder to another drive, Plex also needs to be given that drive: hover over the Plex icon in CasaOS, click the three dots, choose Settings, and add the drive under Volumes.

Already have Plex? Use your existing Plex. Then sign in to Plex in the setup guide, or later on CleanCut's Kids & Plex page.

Use it from your phone or away from home

At home: on your phone or tablet, connect to your home Wi-Fi, open the browser and go to http://<your-server>:8585. Sign in with your parent password. Your browser's menu can add it to your home screen so it opens like an app.

The kids' page: the Kids & Plex page shows a link that ends in /?kids. Open it on your child's tablet. They can search and ask for titles there, and nothing else.

Away from home: CleanCut works with Tailscale, a free app that links your phone and your server through a private, encrypted connection, so you can reach CleanCut from anywhere without changing anything on your router. In CleanCut it's under Settings → Connection → Remote access. (Watching your movies away from home happens in the Plex app, which needs Plex Pass or Plex's Remote Watch Pass for that.)

Phone apps: apps such as Helmarr (iPhone) and nzb360 (Android), and request services such as Seerr, are made for Sonarr and Radarr. CleanCut can let them in, and everything they add is still cleaned before it reaches your kids. Go to Settings → Connection → Phone apps and request services and turn on Allow phone apps and request services. CleanCut then lists the Host, Port, path and API key each app asks for.

The step-by-step guide for both, from installing Tailscale to adding CleanCut in Helmarr, is at shop.harrelsons.org/cleancut/remote.

Other systems

The steps below are for Unraid, Synology, TrueNAS, QNAP, plain Linux, Mac and (in early access) Windows. After installing, open http://<your-server>:8585 and follow the setup guide above. It's the same everywhere.

Movies you already have: on these systems, give CleanCut your existing movie and TV folders by adding them under /media inside CleanCut, for example your movies share as /media/movies. In a compose file that's one more line under volumes:, such as - /volume1/video/movies:/media/movies. Then pick them in the setup guide. See Clean the movies and shows you already have for what CleanCut does to them.

Unraid

1. Copy platforms/unraid-clean-media.xml to /boot/config/plugins/dockerMan/templates-user/my-clean-media.xml on your flash drive (the USB stick Unraid starts from). To reach the flash drive from your computer: it usually appears on your network as a shared folder named flash. Open it from File Explorer (Windows) or Finder (Mac), go into config/plugins/dockerMan/templates-user, and save the file there as my-clean-media.xml. Can't see flash? On Unraid's Main tab, click Flash and set its SMB Export to Yes.
2. Docker tab → Add Container → Template: pick clean-media.
3. Check that Media points at your data share (a share is a shared folder on your server; for example /mnt/user/data). To clean movies you already have, click Add another Path, Port, Variable, Label or Device, choose Path, set Container Path to /media/movies and Host Path to your movies share. Then press Apply.

PUID and PGID are two numbers that tell CleanCut which user account should own your movie files. Unraid's defaults PUID 99 / PGID 100 (nobody/users) are correct for most setups.

Synology (DSM 7.2+, Container Manager)

1. Synology needs the network tunnel driver switched on once (CleanCut uses it for its optional VPN). Go to Control Panel → Task Scheduler → Create → Triggered Task → User-defined script. Set the user to root and the event to Boot-up, and type this as the script:

   insmod /lib/modules/tun.ko
   

   Save it, then select it and press Run once.
2. Go to Container Manager → Project → Create, choose a folder (for example /docker/clean-media), and paste docker-compose.yml.
3. Change /mnt/media/data to your media share (a shared folder on your NAS), for example /volume1/data.
4. Set PUID and PGID to your user. These two numbers tell CleanCut which user account should own your movie files. The usual values are 1026 / 100. To check yours, turn on SSH (a way to type commands on the NAS from your computer) in Control Panel → Terminal & SNMP → Terminal → Enable SSH service. Then, on your computer, open PowerShell (Windows) or Terminal (Mac), type ssh yourname@<nas address>, enter your password, and type id yourname. Use the numbers after uid= and gid=. You can turn SSH off again afterwards.
5. Press Next → Done. Open http://<nas>:8585.

TrueNAS SCALE (24.10+)

1. Go to Apps → Discover Apps, open the three-dot menu, and choose Install via YAML.
2. Name it clean-media and paste docker-compose.yml.
3. Change ./config to a dataset path (a dataset is TrueNAS's name for a storage folder; for example /mnt/tank/apps/clean-media) and /mnt/media/data to your media dataset (for example /mnt/tank/data).
4. Set PUID/PGID (the numbers that tell CleanCut which user account should own your movie files) to the owner of your media dataset (568 = the built-in apps user).
5. Press Save. Open http://<truenas>:8585.

QNAP (Container Station 3)

1. Go to Container Station → Applications → Create and name it clean-media.
2. Paste docker-compose.yml, then change /mnt/media/data to your share (a share is a shared folder on your NAS; for example /share/Media/data) and ./config to /share/Container/clean-media.
3. Press Create. Open http://<nas>:8585.

Raspberry Pi 5 / any Linux with Docker

New to Linux? Installing CasaOS first (see Don't have CasaOS or ZimaOS yet?) and then following the CasaOS steps is the easiest way, on a Raspberry Pi too. The steps below are for typing commands yourself. Type them in the terminal, a window where you type commands. sudo at the start of a command runs it as the administrator, so it may ask for your password.

First, the media drive. Movies need a big drive (a USB SSD or hard drive on a Pi). For CleanCut to manage it properly it should be formatted ext4 (the standard Linux drive format) and mounted (connected to a folder) at the same place every time the computer starts, before Docker starts. A drive formatted for Windows (NTFS) works too. exFAT and FAT32 drives (common on USB drives sold for both Windows and Mac) also work, but they can't use space-saving links (hard links), so downloads are copied instead, and permissions can't be set on them.

1. Plug the drive in and find it: lsblk -f (for example sda1, with its UUID).
2. Only if it's empty or you don't need what's on it, format it (this erases the drive): sudo mkfs.ext4 -L media /dev/sda1.
3. Mount it at boot:

   sudo mkdir -p /mnt/media
   echo 'LABEL=media /mnt/media ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab
   sudo mount -a && sudo mkdir -p /mnt/media/data && sudo chown -R 1000:1000 /mnt/media/data
   

4. Check: df -h /mnt/media shows the big drive's size, not the SD card's.

Then CleanCut:

curl -fsSL https://get.docker.com | sh
mkdir -p ~/clean-media && cd ~/clean-media
curl -fsSLO https://shop.harrelsons.org/cleancut/install/docker-compose.yml
nano docker-compose.yml        # change /mnt/media/data to your media drive
sudo docker compose up -d

nano is a simple text editor that opens inside the terminal. Use the arrow keys to move, change the text, press Ctrl+O and then Enter to save, and Ctrl+X to close it.

Or with plain Docker:

sudo docker run -d --name clean-media --restart unless-stopped \
  --cap-add NET_ADMIN --device /dev/net/tun --stop-timeout 60 \
  -p 8585:8585 -e PUID=1000 -e PGID=1000 -e TZ=America/Chicago \
  -v ~/clean-media/config:/config -v /mnt/media/data:/data \
  ghcr.io/lumblehamb/clean-media-stack:latest

Add -v /path/to/your/movies:/media/movies (and the same for TV) to clean the movies you already have.

Mac, or Windows (Docker Desktop)

CleanCut runs on a Mac or a Windows PC in the free Docker Desktop app. Mac: Apple silicon (M1 or newer) with 8 GB of memory (16 GB recommended). Windows is in early access while we test it on more computers: if you try it, we'd love to hear how it went at ethen@harrelsons.org. For a server that's on all day, a small mini-PC with CasaOS or ZimaOS is still the easiest.

1. Install Docker Desktop, the free app that runs containers on Windows and Mac.
2. Install Plex Media Server from plex.tv on the same computer, the normal way. CleanCut finds it by itself.
3. Make a folder, for example Documents\CleanCut, and save the setup file in it: docker-compose.cleaner.yml to clean the movies and shows you already have (CleanCut Cleaner, and the simplest choice), or docker-compose.yml for CleanCut Suite, which also finds and downloads.
4. Open the file in Notepad (Windows) or TextEdit (Mac) and change /mnt/media to the folder with your movies and shows, for example D:/Media (Windows) or /Volumes/Media (Mac). With docker-compose.yml, also change /mnt/media/data (see the note on space-saving links below).
5. Open PowerShell (Windows) or Terminal (Mac). Type cd (with a space after it), drag your CleanCut folder into the window, and press Enter. Then type docker compose up -d and press Enter (with the Cleaner file: docker compose -f docker-compose.cleaner.yml up -d).
6. Open http://localhost:8585 (localhost means "this computer").

Good to know on Windows and Mac:

• Docker Desktop sets aside about 4 GB of memory for itself. On a Mac with 8 GB, lower it in Docker Desktop → Settings → Resources so the Mac and Plex have room.

• Suite and space-saving links: on Docker Desktop, space-saving links (hard links) only work inside one shared folder. Put your downloads and your library under one parent folder and share only that, for example ~/CleanCut as /data with the library in ~/CleanCut/media. Otherwise CleanCut still works, but new downloads are copied instead of linked.

• Turn on Start Docker Desktop when you sign in (Docker Desktop → Settings → General), and set the computer to never sleep while it's plugged in. Cleaning only happens while it's awake. A MacBook needs to stay plugged in and awake.

• Windows needs virtualization switched on; Docker Desktop's installer checks this and explains how if it isn't. If Windows asks whether to allow Docker through the firewall, allow it, so your phone can reach CleanCut.
• Use a media drive formatted NTFS (Windows) or APFS (Mac), not exFAT. A drive formatted on Windows can only be read on a Mac, not written to.
• CleanCut's Run check-up tells you whether your drive can use space-saving links. If it can't, new downloads are copied into your library, so a title briefly uses twice the space. CleanCut frees the extra copy once it's cleaned (Settings → Downloads → Free up space as soon as a title is cleaned).
• On Windows and Mac, shrinking large videos starts switched off, and backups are kept on your media drive, where you can see them.
• Keep the ./config folder on the computer's own drive (not a network share).

CleanCut Cleaner: the setup file without a VPN

CleanCut Cleaner only cleans the movies and shows you already have, so it doesn't need the VPN's extra permissions (NET_ADMIN and /dev/net/tun) or a download folder. Use docker-compose.cleaner.yml: it mounts just your settings (/config) and your movies and shows (/media). It's the same app as the full file, and your license key decides what it does. The full file works for Cleaner owners too, and the free trial works with either. Upgraded to Suite later? Switch to docker-compose.yml (keep the same ./config folder, so nothing is lost) to add finding and downloading with a VPN.

On CasaOS and ZimaOS, Cleaner owners install the normal CleanCut app from the store.

For experienced users

CleanCut is one container. Whatever your server is, you give it the same few things:

Optional: PUID/PGID (the user that owns your media files, default 1000), TZ (your time zone, for example America/Chicago).

Then open http://<your-server>:8585. The setup guide does the rest.

Minimum hardware: a Raspberry Pi 5 (4 GB) or any 64-bit Intel/AMD computer from the last ~8 years, with 4 GB RAM. Listening mode (speech recognition: CleanCut listens to the audio itself when a title has no subtitles) is much faster with 4+ cores or an NVIDIA card (see Graphics cards below). Keep the /config folder on an SSD if you can: the built-in apps' databases live there. The image is about 3 GB to download.

Want to open Sonarr, Radarr, Prowlarr, Bazarr or qBittorrent directly? Turn on Expert mode under Settings → System → Advanced. Changes made there can break the automatic setup.

Graphics cards (optional, faster)

CleanCut uses the fastest hardware it's given and falls back to the processor by itself. Video is never re-encoded when cleaning, so a graphics card only matters for two background jobs: listening (titles with no subtitles) and shrinking oversized downloads.

Settings → Listening and Settings → Downloads show what's being used.

Updating

Updates are free for life. Your settings, word list and library are kept.

• Installed from the CleanCut store (CasaOS or ZimaOS): new versions arrive through the store. When one is out, your App Store offers an update for CleanCut; click it.
• Custom Install on CasaOS or ZimaOS: hover over the CleanCut icon, click the three dots, and choose Check then update.
• Unraid: when there's a new version, the Docker tab shows update ready next to CleanCut. Click it to apply the update.
• Synology, TrueNAS and QNAP: update CleanCut the way your system updates other containers: pull the newest ghcr.io/lumblehamb/clean-media-stack:latest image, then restart the project or app.
• Docker Compose: docker compose pull && docker compose up -d.

Something not working?

See the troubleshooting guide. The same fixes are in the app under Help, next to a Run check-up button that finds most problems for you.