Installation

Installation

ScreenGuard is a Flutter application with a background daemon, three native C helpers, a Python X11 fallback and a GNOME Shell extension. Pick the install method that matches your distribution.

Package repositories are stable-only. The APT, Arch and Copr repositories always carry the latest stable release. Pre-release packages are only on GitHub Releases — the commands further down install them. Every beta's complete source is public on the beta branch, so you can equally build a beta from source.

Before you start: ScreenGuard needs the daemon running to track anything. Every method below installs it and can enable it to start at login.

---

Debian, Ubuntu, Zorin OS, Linux Mint, Pop!_OS

Option A — APT repository (recommended)

Receives updates with the rest of your system.

sudo wget -O /usr/share/keyrings/screenguard.asc https://adityakrishnan005-a11y.github.io/ScreenGuard/apt/key.asc
echo "deb [signed-by=/usr/share/keyrings/screenguard.asc] https://adityakrishnan005-a11y.github.io/ScreenGuard/apt apt main" | sudo tee /etc/apt/sources.list.d/screenguard.list
sudo apt update && sudo apt install screenguard

Option B — standalone .deb

wget https://github.com/adityakrishnan005-a11y/ScreenGuard/releases/download/v0.1.1/screenguard_0.1.1_amd64.deb
sudo apt install ./screenguard_0.1.1_amd64.deb

---

Fedora, RHEL, Rocky Linux

Copr repository

sudo dnf copr enable the-amibivert/screenguard
sudo dnf install screenguard

Standalone .rpm

sudo dnf install https://github.com/adityakrishnan005-a11y/ScreenGuard/releases/download/v0.1.1/screenguard-0.1.1-1.x86_64.rpm

---

Arch Linux, Manjaro

The AUR package is pending. Until it lands, use the signed custom repository.

# 1. Import and locally trust the signing key
curl -fsSL https://adityakrishnan005-a11y.github.io/ScreenGuard/arch/key.asc -o /tmp/screenguard.asc
sudo pacman-key --add /tmp/screenguard.asc
sudo pacman-key --lsign-key 5E851C89E39A8FD573BF40EAEC671823CA28A37E

# 2. Append the repository to /etc/pacman.conf:
#    [screenguard]
#    Server = https://adityakrishnan005-a11y.github.io/ScreenGuard/arch/$arch
#    SigLevel = Required DatabaseRequired TrustedOnly

# 3. Install
sudo pacman -Sy && sudo pacman -S screenguard

---

Any distribution — tarball

Useful on exotic distros, on systems without systemd, or if you want to run it without touching the system package database.

wget https://github.com/adityakrishnan005-a11y/ScreenGuard/releases/download/v0.1.1/screenguard-0.1.1-x86_64.tar.gz
mkdir -p screenguard-0.1.1
tar -xzf screenguard-0.1.1-x86_64.tar.gz -C screenguard-0.1.1
cd screenguard-0.1.1
./install.sh                 # installs to ~/.local
./install.sh --system        # installs to /usr/local (needs sudo)

install.sh options:

Flag	Meaning
--prefix DIR	Install somewhere other than ~/.local
--system	Install to /usr/local (requires root)
--yes	Non-interactive; assume "yes" to the autostart question
--no-daemon	Copy the files but do not touch the service
--uninstall	Remove the install (your database is kept)

---

After installing

1. The daemon

The .deb and .rpm packages ship a systemd user preset, so the service is enabled automatically on install and on login. Verify it:

systemctl --user status screenguard    # expect: active (running)

If you installed from a tarball, install.sh offers to set it up: a systemd user service where systemd is available, and an XDG autostart fallback where it is not (OpenRC, runit and other non-systemd systems). To do it by hand:

systemctl --user enable --now screenguard

The daemon is what actually tracks usage and enforces limits. Without it the GUI opens but nothing is recorded.

2. GNOME Wayland — enable the shell extension

gnome-extensions enable screenguard@screenguard.app

The package post-install step enables AT-SPI accessibility, copies the extension into place, and — on Fedora and friends — discovers your active desktop sessions in /run/user/* so the service can be enabled immediately. On Arch, or if you installed from a tarball, run it once yourself:

sudo /usr/share/screenguard/enable_fedora_a11y.sh

If tracking still shows unknown, see Troubleshooting.

3. X11 — install the helper tools

sudo apt install xdotool xorg-xprop xprintidle    # Debian/Ubuntu
sudo dnf install xdotool xorg-x11-utils xprintidle # Fedora

xdotool is used to minimise and close windows when a limit is hit, xprop to read the active window and xprintidle for idle detection. Tracking itself works without them, but enforcement does not.

4. Launch it

screenguard

or start it from your applications menu. On first launch, ScreenGuard offers to set the daemon up for you — choosing Run permanently enables autostart at login.

---

Upgrading

Package-managed installs upgrade with your package manager:

sudo apt upgrade screenguard      # Debian/Ubuntu
sudo dnf upgrade screenguard      # Fedora
sudo pacman -Syu screenguard      # Arch

ScreenGuard also updates itself: Settings → Updates can download and install a new version in place. Turn it off if you prefer managing versions yourself.

Beta users must remember that beta releases are hidden by default — enable Include Beta Versions in Settings → Updates to see them.

---

Uninstalling

# Package-managed
sudo apt remove screenguard     # Debian/Ubuntu
sudo dnf remove screenguard     # Fedora

# Tarball
./uninstall.sh

Your usage database at ~/.local/share/screenguard/ is left untouched on uninstall — delete it by hand if you want it gone.

---

Building from source

See Development.

---

Related: Getting Started · Troubleshooting · Packaging and Releases