# 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):
   ```bash
   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:

```bash
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.