Family Screen Time · Computer setup

Back to computers

Start with observe mode

  1. On the computer to connect, open Computers → Add computer.
  2. Name the computer and choose the Linux account to manage. Leave the username empty to use the account running sudo.
  3. Download the configured installer. Run sudo python3 ~/Downloads/family-screen-time-install.py locally. Review the script before running it if you wish.
  4. Confirm that the computer appears online. Check usage, lock/unlock detection and manual pause receipt in observe mode. Observe mode does not block login or terminate sessions.
  5. Delete the downloaded installer. Its pairing token is single use and expires after 15 minutes.

Supports x86_64 Ubuntu and Bazzite with Python 3.12 or newer. The current Ubuntu target is 26.04 LTS. Bazzite means its normal desktop, including desktop Steam.

Enable login enforcement separately

Keep a root console open. Create a distinct parent administrator account and confirm its login and sudo work. The managed child account should not have administrator access. This setup requires review on the actual desktop/display manager.

Run preflight with the real account names:

sudo python3 /var/lib/family-screen-time/app/install/installer.py preflight --user CHILD --parent PARENT

Review the detected PAM services, automatic login, fingerprint login, TTY, SSH and su paths. Test recovery in a disposable VM first. On Ubuntu, after completing the parent and PAM checks:

sudo python3 /var/lib/family-screen-time/app/install/installer.py enable --user CHILD --parent PARENT --services REVIEWED_SERVICES --parent-login-tested --pam-paths-reviewed

Replace REVIEWED_SERVICES with the comma-separated services you actually reviewed. Immediately verify that the child is denied when paused and the parent can still log in.

Bazzite

First build and install the distribution gate RPM with rpm-ostree and reboot. The gate belongs at /usr/libexec/family-screen-time/login-gate. Validate execution with SELinux enforcing. Add --selinux-execution-tested to the enable command only after that test passes. The configured installer and automatic updater do not layer RPMs, change SELinux or reboot the computer.

The Bazzite gate package and authentication flow are not yet certified on a real Bazzite system.

Updates and recovery

Updates wait until all managed-account sessions are signed out. The hourly updater downloads authenticated manifests and verifies their device signature, expiry, archive checksum and safe file paths. It updates only agent/helper application files, preserving the journal, config, native login gate and PAM rules. The previous version is retained and restored if the new agent fails its local heartbeat health check.

Pause automatic updates under each computer's settings. To check and apply an allowed update locally:

sudo systemctl start family-screen-time-update.service
sudo journalctl -u family-screen-time-update.service -n 30

The first command checks and applies an allowed update. To check only, use:

cd /var/lib/family-screen-time/app
sudo python3 -m screentime.updater --check

Do not delete pairing or journal files to troubleshoot an update. Allowance records are preserved. After a failed activation, automatic retries of the same release stop. Review the service logs and recovery status before manually retrying with sudo python3 -m screentime.updater --retry. If recovery itself fails, use a retained administrator console; the dashboard reports that recovery is needed.

For bounded parent recovery:

cd /var/lib/family-screen-time/app
sudo python3 -m screentime.agent recover --minutes 15 --reason "Parent recovery"

Root access can bypass these controls. Uninstall removes only owned PAM entries, retaining unrelated changes, config, journals and recovery records:

sudo python3 /var/lib/family-screen-time/app/install/installer.py uninstall