Currently, shepherd-launcher only provides a desktop environment and tools for installing itself. You'll have to take care of everything else yourself:

1. Install desktop Linux.
2. Set up a child user account.
3. Install appropriate content for the child user account from a standard desktop environment.
4. Install shepherd-launcher for the child user account.
5. Write configuration for your content.

1. Install Linux

shepherd-launcher requires a Linux that supports both Wayland and GTK4 Layer Shell. At this time, we recommend Ubuntu 26.04.

If installing from scratch, we recommend the following:

• If you enable full-disk encryption, either do so using the TPM to unlock or via a keyfile on a USB stick for ease-of-use.
• The first user account is for an adult administrator, not the unprivileged child. Make sure to set a secure password!
• If you have an NVIDIA graphics card, install the proprietary drivers during setup.

2. Set up child account

This can be done via adduser or in the Settings app. Make sure that the child is a regular user and not a superuser to avoid the possibility of them exiting the shell (though if they figure out how to escalate by switching to the TTY and reconfiguring in text mode, you have different problems a budding software engineer on your hands).

3. Install child content

Content-specific examples are described in the "Content examples" section of this Wiki, but in general you'll have to do the following:

1. While in the administrator account, install dependencies (i.e. any Snaps, Flatpaks, apt packages, or similar).
2. In the child account, in a "standard" desktop environment, fully set up the content (i.e. log into Steam and install games, put content ROMs in a known location, set up virtual machines).

4. Install shepherd-launcher itself

If you're using Ubuntu 25.10 or higher, this can be done from the administrator account via the ./scripts/shepherd script as described in INSTALL.md.

Once installed, do the following:

1. Log out or switch user.
2. Choose the child account but do not sign in yet.
3. Pick the "Shepherd Kiosk" session (if using GDM as your display manager, the session picker is a gear in the bottom right).
4. Sign in.

You may also want to set the child user to automatically sign in and use the hardening script to remove the possibility of exiting the shell entirely.

5. Write configuration

The installation script creates an example configuration in ~/.config/example/shepherd.toml. The full documentation for the format is described in the shepherd-config crate, and content-specific examples are described in the "Content examples" section of this Wiki.