Your server.
Their kids.
Everyone in control.

Check what you need

Make sure you have everything in What you need, then check that Docker works on the machine that will run KidsWatch:

docker version
docker compose version

If either says permission denied, put sudo in front of every Docker command on this page. Do not change the Docker socket's permissions to get around it.

Download it

Get the source, copy the example files, and create the folders the app uses:

git clone https://github.com/pughouselabs/kidswatch-for-plex.git
cd kidswatch-for-plex
cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
sudo install -d -o 1000 -g 1000 -m 0700 data secrets

Point it at your Plex settings file

In docker-compose.yml, replace /path/to/plex/Preferences.xml with your server's existing file. On Linux it is usually under /var/lib/plexmediaserver/Library/Application Support/Plex Media Server/. For Plex in Docker, look in the folder mapped to Plex's /config.

The app runs as user 1000 and mounts the file read-only. Give user 1000 read access, but do not make the file readable by everyone, and never copy what is in it into .env.

Fill in your settings

Edit .env. These are the settings most people change:

Set up your sign-in codes

Your admin sign-in needs a six-digit code sent to your phone, and sign-in stays blocked until delivery works. Make a private webhook, for example a Home Assistant automation that sends a phone notification, and save its full URL in your password manager. Then put that URL in secrets/notification_url, owned by user 1000 with mode 600, without typing it into a command. The README (coming soon) has the Home Assistant recipe and a test command.

Start it and pick the kids' libraries

docker compose config --quiet
docker compose up -d --build
docker compose ps

Run the README's library listing command (coming soon). It prints each library's key, name and type without showing your token. Put the movie and TV keys in PK_KID_SECTIONS, then apply the change:

docker compose up -d --force-recreate kidswatch

After any .env change, use this command. A plain docker compose restart keeps the old settings.

Check that it is ready

curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/readyz

The second check passes only when Plex, your libraries and the time keeper are all working. Give a fresh install a few seconds. If it keeps failing, read the logs with docker compose logs --tail=50 kidswatch.

Put it behind HTTPS

The app only listens on the Docker host itself, on port 8080. Keep it that way and let a reverse proxy serve your address. With Caddy installed on the same host, back up /etc/caddy/Caddyfile and add:

kids.example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
        header_up -CF-Connecting-IP
        header_up -CF-IPCountry
    }
}

Then run sudo caddy validate --config /etc/caddy/Caddyfile and sudo systemctl reload caddy. Caddy gets the certificate for you. Other proxies work too, as long as they replace the visitor address headers instead of passing them through. A proxy running in Docker should join a private network with the app and use kidswatch:8080.

Sign in for the first time

Open your HTTPS address and sign in with the Plex server owner's account, then enter the code sent to your phone. On the Admin page, turn on a parent. Connect and approve a test child, check what that child sees in Plex, and test that a real video stops before you rely on the limits.