Skip to content
Frostyard docs

pilothouse

The pilothouse extension adds Pilothouse, a web administration console, to a Frostyard bootc image. It manages the machine through Updex and the container engines it finds. Use it when you want a browser view of extensions and containers. Every image carries the extension’s definition, switched off. The extension itself is not in the image: Updex turns it on and downloads it.

Before you start

Section titled “Before you start”

You need:

  • A Frostyard bootc image. Every image built on Base has systemd-sysext and frostyard-updex.
  • Root access to enable, update, and remove the extension.
  • Network access to https://repository.frostyard.org/ext/pilothouse/.
  • Free space in /var for the image.

pilothouse has no published test results on Frostyard images yet. Try it on a machine you can spare first.

Enable pilothouse

Section titled “Enable pilothouse”

See what Updex found, then enable the feature and download it now:

Terminal window
updex features list --component=pilothouse
sudo updex features enable pilothouse --now

pilothouse appears as a component, with its feature disabled. The enable command downloads the image, checks its checksum and signature, links it, and refreshes the merge.

Check the merge and the commands and the services:

Terminal window
systemd-sysext status
command -v pilothouse pilothoused
systemctl status pilothoused.service pilothouse.service

systemd-sysext status lists pilothouse, both names print a path, and both units are active.

If enable --now exits with a refresh error (refresh_error in JSON), the download worked, but the activation did not. If the output says activation did not finish, the extension is merged, but users and groups can be missing: reboot. Otherwise the merge state is unknown: reboot. A sudo systemd-sysext refresh by hand does not create users and groups. Then run the checks above again.

Use pilothouse

Section titled “Use pilothouse”

Both services start at boot. pilothouse.service is the web UI. It listens on 127.0.0.1:8888, so you open it from this machine:

http://127.0.0.1:8888

Sign in with a non-root account of this machine and its password. Root cannot sign in. Every signed-in account can view. Members of the sudo group can make changes.

pilothoused.service is the root broker. It listens on /run/pilothouse/broker.sock for members of the pilothouse group. It treats members of the sudo group as administrators. It checks admin actions through the pilothouse PAM service. A tmpfiles rule copies /etc/pam.d/pilothouse from /usr/share/factory/etc/pam.d/pilothouse at boot, or on a refresh by Updex v2.1.3 and later, when the file is missing.

Frostyard starts the broker with these backends switched on: Updex (/usr/bin/updex), the Podman socket (/run/podman/podman.sock), the Docker socket (unix:///var/run/docker.sock), Incus, and k3s (/usr/bin/k3s). A backend whose program or socket is missing does not stop the broker. Merge the Podman, Docker, Incus, or k3s extension to give Pilothouse something to manage.

Update, roll back, and remove

Section titled “Update, roll back, and remove”

Check for an update, then install it:

Terminal window
updex features check --component=pilothouse
sudo updex features update --component=pilothouse

Updex downloads and verifies the new image, switches the link, deletes older versions, and refreshes the merge. See Manage system extensions for --no-vacuum, --dry-run, and the update timer. The refresh swaps /usr under the running system.

Roll back with sudo updex features rollback pilothouse. It takes effect at the next boot. See Roll back.

Remove pilothouse:

Terminal window
sudo updex features disable pilothouse --now --force

Updex unmerges all extensions on the host, deletes the image, and merges the rest again. The two services and their commands go. Reboot when the command finishes. Without --force, Updex refuses while the image is merged.

What ships

Section titled “What ships”
Item What you get
Package frostyard-pilothouse, from the upstream release, installed into the image with dpkg. The build checks the download against a pinned checksum, and checks that its dependencies are met before it installs
Commands /usr/bin/pilothouse and /usr/bin/pilothoused
PAM service /etc/pam.d/pilothouse, from /usr/share/factory/etc/pam.d/pilothouse
User and group pilothouse, created at boot, or by a refresh from Updex v2.1.3 and later
Broker command pilothoused --socket /run/pilothouse/broker.sock --socket-group pilothouse --admin-group sudo --updex /usr/bin/updex --podman-socket /run/podman/podman.sock --docker unix:///var/run/docker.sock --incus --k3s /usr/bin/k3s
Version The image file name carries the frostyard-pilothouse package version, plus a +rN snosi revision when one is set
Image file pilothouse_<version>_<os>_<arch>.raw.zst; .raw.xz, .raw.gz, and .raw also work
Download From https://repository.frostyard.org/ext/pilothouse/, signature required (Verify=true), into /var/lib/extensions.d/
Services pilothoused.service and pilothouse.service, on at boot

Each build checks the two commands, both service units, the sysusers file, the factory PAM file, and the tmpfiles, preset, backend, and activation files. A build that is missing one fails.

See also

Section titled “See also”

Sources

Section titled “Sources”

Reviewed 2026-10-27; Updex facts reviewed 2026-10-30. snosi commit b2858ca0222814c395cf8248db98f3e096d57dc9; Updex v2.1.3 commit 2661e987faac986f2594d1d9bbbadf1bf3053f5b.