shepherd-launcher

A child-friendly, parent-guided launcher for Wayland, allowing supervised access to applications and content that you define.

Its primary goal is to return control of child-focused computing to parents, not software or hardware vendors, by providing:

• the ease-of-use of game consoles
• access to any application that can be run, emulated, or virtualized in desktop Linux
• with granular access controls inspired by and exceeding those in iOS Screen Time

While this repository provides some recipes for existing software packages (including non-free software), shepherd-launcher is non-prescriptive: as the end user, you are free to use them, not use them, or write your own.

Screenshots

TODO:

• home screen at different times showing different applications
• modern proprietary application showcase (Minecraft, individual Steam games)
• emulated application showcase (ScummVM games, 90s edutainment on Win9x, Duolingo via Waydroid)
• externally managed Chrome container for access to school resources
• media showcase (local storage and individual titles from streaming services)
• time limit popup
• "token" system

Installation

tl;dr:

1. any Linux with Wayland (optional: TPM-based FDE plus BIOS password to prevent tampering)
2. System dependencies:
   • Ubuntu/Debian: apt install build-essential pkg-config libglib2.0-dev libgtk-4-dev libcairo2-dev libpango1.0-dev libgdk-pixbuf-xlib-2.0-dev libwayland-dev libx11-dev libxkbcommon-dev libgirepository1.0-dev libgtk4-layer-shell-dev librust-gtk4-layer-shell-sys-dev sway swayidle
3. Rust (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)
4. Set up cgroups for process management (one-time, requires root):

   sudo ./setup-cgroups.sh
   

5. binaries (TODO: deployable package that depends on Sway and installs the config)
6. test session on login
7. configure auto-login to this session

cgroups Setup

The shepherd daemon uses Linux cgroups v2 to reliably terminate all processes when a session ends. This is essential for applications like Minecraft that spawn child processes which may escape traditional process group signals.

Run the setup script once after installation:

sudo ./setup-cgroups.sh

This creates /sys/fs/cgroup/shepherd with appropriate permissions for your user. The directory is not persistent across reboots on most systems, so you may want to add this to your system startup (e.g., in /etc/rc.local or a systemd unit).

Usage

TODO: open lid; play

Core concepts

• Launcher-first: only one foreground activity at a time
• Time-scoped execution: applications are granted time slices, not unlimited sessions
• Parent-defined policy: rules live outside the application being run
• Wrappers, not patches: existing software is sandboxed, not modified
• Revocable access: sessions end predictably and enforceably

Recipes

TODO

• .desktop syntax plus rules (time allowance, time-of-day restrictions, network whitelist, etc.)
• wrappers for common applications
• how to write a custom wrapper or custom application

Development

tl;dr:

• Run in development: ./run-dev
• Set the SHEPHERD_MOCK_TIME environment variable to mock the time, such as SHEPHERD_MOCK_TIME="2025-12-25 15:30:00" ./run-dev
• Run tests: cargo test
• Lint: cargo clippy

Contributing

shepherd-launcher is licensed under the GPLv3 to preserve end-users' rights. By submitting a pull request, you agree to license your contributions under the GPLv3.

Contributions written in part or in whole by generative AI are allowed; however, they will be reviewed as if you personally authored them.

The authors of shepherd-launcher do not condone software or media piracy. Contributions that explicitly promote or facilitate piracy will be rejected. Please support developers and creators by obtaining content legally.