d77void Immutable Docs

This is the community documentation of d77void Immutable: a Void Linux with runit and without systemd, where the system is a read-only image that is replaced as a whole on every update, with the previous version always there to go back to.

These pages explain how the system really works and how to run it and recover it yourself. Every procedure here is checked against the system’s code and, where it says so, on real installations.

Work in progress. d77void Immutable is heading for a Technology Preview on 6 January 2027. It installs, boots and updates itself on real hardware, but it is still a test system.

Where to start

• New to immutable systems? Read What d77void Immutable is.
• Want to know what happens when it updates? Read A/B slots and updates.
• Not sure an update went through? Follow Checking an update.
• Something broke? Start with Recovery or Common problems.
• Looking for a program? See Where to install applications.

Not affiliated with Void Linux

d77void Immutable is not affiliated with or endorsed by the Void Linux project or its maintainers. For general Void Linux topics, the Void Linux Handbook applies; these pages only cover what is different here.

License

This documentation is licensed under CC BY-SA 4.0.

What d77void Immutable is

d77void Immutable is a variant of d77void where the operating system is a single read-only image. You do not install or update packages one by one: a new version of the whole system arrives as a new image, and the previous one stays on the disk so you can go back to it.

“Immutable” means the same here as on Fedora Silverblue: the system files do not change while it runs, but your settings, your data and your applications are kept.

• Base: Void Linux (glibc, x86_64) with runit. There is no systemd.
• Desktop: KDE Plasma.
• Applications: Flatpak (Discover and Flathub) for graphical programs, Distrobox for command-line and development tools. See Where to install applications.
• Updates: automatic, whole-image, signed, with automatic fallback. See A/B slots and updates.

How it differs from a regular Void installation

xbps-install is present in the image, but it cannot change anything: the system’s files and the package database are read-only. That is expected, not an error. Use the methods in Where to install applications instead.

What is read-only and what is kept

At boot, the system puts together its root directory from the image of the version being started and from the persistent data on the disk:

The kept data is the same whichever version you start: going back to the previous version keeps your files and settings.

Changes to /etc are kept, but a file you change stops following new versions of the image; d77-etc-diff shows and undoes those changes. See What is kept for the details.

Things that work differently

• Do not copy programs into /usr or /opt. /usr is read-only, and /opt is emptied on every boot. Put them in your home, or use one of the methods in Where to install applications.
• Changes to the system itself come with a new version, not by editing it on the running machine.
• Restarting is how an update takes effect. The new version is downloaded in the background and starts on the next boot.

A/B slots and updates

d77void Immutable keeps two complete versions of the system on the disk, in two slots called A and B. One of them is the version you use; the other holds the previous version, or the new one waiting to be started.

The letters say nothing about age. After an update the newest version can be in A or in B: what matters is which slot is running, which one is confirmed, and whether one is waiting to be tried.

What is on the disk

The installation has one main partition (labelled d77), plus an EFI system partition on UEFI machines. On the running system the d77 partition is mounted at /run/d77/disk:

/run/d77/disk/
├── slots/
│   ├── A/   root.sqfs  vmlinuz  initramfs  manifest.json
│   └── B/   root.sqfs  vmlinuz  initramfs  manifest.json
├── state/   your /etc, /var and /root changes
├── home/    your /home
└── boot/    GRUB, on Legacy BIOS machines only (on UEFI it is on the EFI partition)

Each slot has the system image (root.sqfs), its kernel and initramfs, and a manifest.json that records which version it holds. The manifest is the last file written to a slot, so a slot without one is not complete.

The data in state/ and home/ is shared by both slots. See What is read-only and what is kept.

Three words to keep apart

Normally the running slot is the confirmed slot. The other slot is the previous version.

How an update happens

1. Looking for a new version. A system service, d77-update, looks for a new version 10 minutes after each boot and then every 6 hours (30 minutes after a failure, such as no network). Nothing is done in the live session or in a factory boot (see The GRUB menu).

2. Downloading into the other slot. If there is a newer version, it is downloaded into the slot that is not running. The running system is never touched. This only happens while the running slot is the confirmed one, so the version you can fall back to is never overwritten.

   The download is about 3 GB. If the connection drops, or you switch the computer off, it continues later from where it stopped.

3. Checking it. Before the new slot is offered, its signature (minisign), size and SHA-256 are checked against what was published. Anything that does not match is thrown away.

4. Getting it ready. The kernel and initramfs are taken from the new image, the manifest is written last, and GRUB is asked to try the new slot once on the next boot.

5. The notice. Plasma shows “Update ready”. It stays on the screen until you close it. Nothing changes until you restart.

6. The trial boot. On the next boot GRUB starts the new version. It clears the request before starting it, so the new version is tried only once.

7. Confirmation. Once the login screen (SDDM) has been up for 15 seconds and the system’s checks pass, the d77-boot-ok service makes the new slot the confirmed one. From then on it is the version started by default.

If the new version does not start

If the new version never reaches the login screen (a broken kernel, a damaged image, a hang), it is never confirmed. On the next boot (after a forced power off, if it hung) GRUB starts the confirmed slot again, which is the version you had. Plasma then shows “Update did not start”. Your files and settings are not affected.

The GRUB menu

The menu shows for 5 seconds:

The factory entry is for recovering from a setting that stops the system from working: the image’s configuration is used, your user accounts still work so that you can log in, and your real settings on the disk are left as they were.

Starting the previous version does not change which slot is confirmed: the next normal boot starts the confirmed one again. In versions published from 18 October 2026 on, Plasma shows “Previous version in use” when the running slot is not the confirmed one, so that it never happens unnoticed.

Update settings

The defaults are in /usr/share/d77/update.conf. To change them, write the setting in /etc/d77/update.conf, which is kept across versions:

sudo mkdir -p /etc/d77
echo 'POLICY=check' | sudo tee /etc/d77/update.conf

With POLICY=check, download a version when you want it with:

sudo d77-update stage --now

Where versions come from

Versions are published on SourceForge and signed with minisign. The system only accepts files signed with one of its trusted keys, in /usr/share/d77/. Only the three most recent versions stay published. Version numbers look like 20261015.1: the date, then a counter for that day.

To check how to see all of this on your own machine, follow Checking an update.

Checking an update

When to use this

• After restarting for an update, to confirm the new version is the one running and that it was confirmed.
• When you expected an update and saw no notice.
• When something looks odd: a version you did not expect, or an update that did not start.

Read A/B slots and updates first if the words running, confirmed and on trial are new to you.

What to expect

On a healthy system, the running slot and the confirmed slot are the same, and grubenv has no trial pending. While an update is being downloaded, a partial file grows in the other slot. After the restart, the other slot is running and, about 15 seconds after the login screen appears, it becomes the confirmed one.

Procedure

Run these in Konsole. The commands with sudo ask for your password.

1. Which version is running

grep IMAGE_VERSION /etc/os-release

IMAGE_VERSION="20261015.1"

2. Which slot is running

cat /proc/cmdline

Look for d77.slot=. For example, d77.slot=A means this boot started slot A. If the line also contains d77.pristine, this is a factory boot.

3. Which slot is confirmed, and whether a trial is pending

On a UEFI machine:

sudo grub-editenv /boot/efi/boot/grub/grubenv list

On a Legacy BIOS machine (including coreboot with SeaBIOS):

sudo grub-editenv /boot/grub/grubenv list

d77_slot=A
d77_try=
d77_trying=

4. Which version each slot holds

jq -r .version /run/d77/disk/slots/A/manifest.json /run/d77/disk/slots/B/manifest.json

One version per line, slot A first. A slot that has never held a complete version has no manifest and gives an error instead.

5. Whether a new version is published, downloading or ready

Ask the server whether there is something newer than the running version:

d77-update check

It prints available <version>, current <version> (you have the latest) or disabled (POLICY=disabled).

A version that is downloaded and waiting for a restart is recorded here:

cat /run/d77/update-ready

To see a download in progress, list the partial file; run it again a minute later and the size should have grown:

sudo ls -l /run/d77/disk/slots/*/root.sqfs.*.part

“No such file” means nothing is downloading: either there is nothing new, the download has finished, or it has not started yet (the first look of a boot waits 10 minutes).

6. What the update service did

sudo tail -n 20 /var/log/d77-update/current

Each line starts with the time, in UTC. Common lines:

sudo tail -f instead of sudo tail -n 20 keeps showing new lines as they arrive; press Ctrl+C to stop it. It never ends by itself.

7. What happened at boot

sudo tail -n 20 /var/log/d77-boot-ok/current

How to read the results

If something goes wrong

• The new version does not start. Do nothing special: switch the computer off and on again if it hung. The next boot goes back to the confirmed version on its own.
• A setting you changed stops the system from working. Choose d77void (factory /etc and /var, changes not kept) in the GRUB menu, then undo the change; see Recovery.
• You keep landing on the previous version without choosing it. See Recovery. Note the output of steps 2 and 3 and of step 7, and report it.

What is kept, and what an update changes

The system you see at boot is put together from two layers: the image of the version being started, which is read-only, and the persistent data on the disk, which is the same for both slots.

Path by path

Your changes to /etc and /var are stored in /run/d77/disk/state/etc/upper and /run/d77/disk/state/var/upper; your home in /run/d77/disk/home. You never need to touch these folders directly.

Where common things live

How /etc follows new versions

/etc starts from the image’s files, with your changes on top:

• A file you changed keeps your version, in every later version too. Your copy hides the image’s copy, so a fix the new image brings to that file does not reach you.
• A file you never changed always follows the current image. On every boot, copies identical to the image’s are dropped, so editing a file and then putting it back exactly as it was also lets it follow the image again.
• A file you added stays.
• A file you deleted stays deleted.
• User accounts: new system accounts and groups that a new version brings are added to your passwd, group, shadow and gshadow. Existing entries, including your users and passwords, are never changed.

Seeing and undoing your changes

d77-etc-diff

lists every file in /etc that differs from the image, one per line:

Run it with sudo to also see the files only root can read.

To see what differs in one file (the image’s version first, then this system’s):

d77-etc-diff sddm.conf.d/10-d77.conf

To put a file back exactly as the image has it (a changed or deleted file is copied back, an added one is removed):

sudo d77-etc-diff --reset sddm.conf.d/10-d77.conf

Paths can be relative to /etc, as above, or absolute (/etc/sddm.conf.d/10-d77.conf). --reset refuses the user accounts (passwd, group, shadow, gshadow, …) and /etc/fstab, which the installer wrote for this machine.

Going back to the previous version

Both slots use the same /etc, /var, /home and /root. Starting the previous version keeps your files, your applications and your settings.

One consequence: a setting you change while running the new version is still there if you go back. If a change made with the new version stops the previous one from working, undo it with d77-etc-diff --reset, or use the factory boot described in Recovery.

Recovery

Most problems on d77void Immutable are undone without reinstalling: the previous version is still on the disk, the system’s own files cannot be damaged, and your changes to the configuration can be bypassed or undone one by one.

Pick the case that matches.

An update did not start

What you see: after restarting for an update, the computer hangs, shows errors, or never reaches the login screen.

What to do: nothing special. If it hangs, hold the power button to switch it off, then switch it on again.

What happens: the new version was started on trial, only once. Because it never reached the login screen, it was never confirmed, so the next boot starts the confirmed version again: the one you had before the update. Plasma then shows “Update did not start”. Your files and settings are not affected.

Check it with Checking an update: the running slot and the confirmed slot are the old one again, and the boot log has a line like slot A failed its trial, back on slot B.

The new version starts, but something does not work

What to do: in the GRUB menu, which shows for 5 seconds when the computer starts, choose d77void (previous version).

This starts the other slot, with the version you had before, and the same files and settings. It changes nothing on the disk: the next normal boot starts the confirmed version again. To stay on the previous version, choose the entry on every boot until a fixed version is published.

The entry only shows when the other slot holds a complete version: after the first update, and not while a new version is being downloaded into it.

Please report what did not work, with the version numbers from Checking an update.

A setting stops the system from working

What you see: after changing something in /etc (a configuration file, a service, the display manager), the system no longer starts properly, or you cannot log in to the desktop.

What to do:

1. In the GRUB menu, choose d77void (factory /etc and /var, changes not kept).

   This starts the confirmed version with the image’s own /etc and /var, as on a fresh installation, held in memory. Your user accounts and passwords, and sudo rights, are carried over so that you can log in. Nothing you change in this boot is kept, and your real settings on the disk are left as they were. Updates do not run in this mode.

2. Log in, open Konsole and list your changes to /etc:

   sudo d77-etc-diff
   

   This lists what differs between the image and your real settings on the disk, not the factory ones in use in this boot. Look for the file you changed. To read your version of it, look at the copy on the disk, for example sudo cat /run/d77/disk/state/etc/upper/sddm.conf.d/10-d77.conf (in this boot, /etc itself shows the image’s version).

3. Still in the factory boot, remove your copy of that file from the disk. Your changes to /etc are stored as files in /run/d77/disk/state/etc/upper; without your copy, the image’s version is used again from the next boot on. For example, for /etc/sddm.conf.d/10-d77.conf:

   sudo rm /run/d77/disk/state/etc/upper/sddm.conf.d/10-d77.conf
   

   Never remove passwd, group, shadow, gshadow, subuid, subgid, sudoers.d or fstab from that folder: they hold this computer’s users, passwords and disks, and without them nobody can log in.

4. Restart normally.

On a system that still starts, the same is done more safely with sudo d77-etc-diff --reset <path>, which refuses the accounts and fstab; see What is kept.

Not yet verified on a real installation: this procedure follows from how the factory boot and d77-etc-diff are written (the factory boot keeps the disk mounted at /run/d77/disk, and d77-etc-diff reads your changes from there), but it has not been tried end to end yet.

A service misbehaves

Restart it, stop it or disable it with runit; see Services. Services that are part of the image come back with their image configuration when you --reset their files.

You keep landing on the previous version

What you see: Plasma shows “Previous version in use” (versions published from 18 October 2026 on), or Checking an update shows a running slot different from the confirmed one, and you did not choose the previous version in the menu.

This happened when the computer was started by another boot loader that then loaded d77void’s menu, such as the GRUB built into Libreboot. Versions published from 18 October 2026 on read GRUB’s settings correctly from any boot loader, and fix the menu of an existing installation by themselves once they have been confirmed. Restarting through the computer’s normal boot path starts the confirmed version.

If it keeps happening on a recent version, please report it with the output of steps 2, 3 and 7 of Checking an update.

What cannot break

• The system’s own files (/usr) are read-only and come from a signed image; nothing on the running system can change them.
• A download that fails or is corrupted is thrown away before it is ever offered; the slot you are using is never written to by an update.
• The version you fall back to is never overwritten: a new version is only downloaded while the running version is the confirmed one.

Where to install applications

The system image is read-only, so programs are not installed into it. There are three ways to add software, each kept outside the image and untouched by system updates:

Try them in that order: Flatpak first, Distrobox when there is no Flatpak or the tool is for the terminal, AppImage when it is the only option.

Flatpak

Flatpak is the main way to install desktop applications. Discover (the Plasma software centre) uses Flathub, which is already set up. Firefox is installed from Flathub on the first boot with a network connection.

Flatpak applications live outside the image, so they stay installed across system updates and when you go back to the previous version.

From the terminal:

flatpak search libreoffice
flatpak install flathub org.libreoffice.LibreOffice
flatpak update
flatpak list --app
flatpak uninstall org.libreoffice.LibreOffice

Flatpak applications are updated through Discover or flatpak update, separately from the system’s own updates.

Limitations. Applications run in a sandbox and see only the folders and devices they are allowed to. If an application cannot open a folder or a device, its permissions can be changed with Flatseal (also on Flathub).

Distrobox

Distrobox gives you a full Linux distribution in a container, with a working package manager, sharing your files and your display with the system. The read-only system is never touched. It uses Podman, without root.

A Void container whose home is a separate folder, so its settings stay out of yours:

mkdir -p ~/boxes/Void
distrobox create --name void \
  --image ghcr.io/void-linux/void-glibc-full:latest \
  --home ~/boxes/Void \
  --unshare-process
distrobox enter void

Inside it, packages install as on a regular Void:

sudo xbps-install -S htop

The first create downloads the image and the first enter sets the container up, so both take a while. Any other distribution works too, for example docker.io/library/debian or quay.io/fedora/fedora.

A graphical program installed inside the container can be added to the system’s menu by running, inside the container:

distrobox-export --app <program>

On d77void Immutable every new container gets its own processes, as with --unshare-process; without that, distrobox stop hangs on a system without systemd. The option is in the recipe so that it works on other systems too.

Containers and their files live in your home, so they are kept across system updates.

AppImage

An AppImage is a single file that contains a program. Keep it in your home, for example in ~/Applications, make it executable and run it:

mkdir -p ~/Applications
mv ~/Downloads/Program.AppImage ~/Applications/
chmod +x ~/Applications/Program.AppImage
~/Applications/Program.AppImage

The image includes what most AppImages need to start (FUSE 2, with libfuse.so.2 and fusermount). To get menu entries and keep them tidy, Gear Lever (on Flathub) manages AppImages for you.

Not yet verified on an installed system. The pieces AppImages rely on are in the image, but running an AppImage has not been tested on a real installation yet. If you try one, please report whether it worked.

AppImages do not update themselves unless the program has its own updater; Gear Lever can help with that.

What does not work, and why

• sudo xbps-install on the system. The system’s files and package database are read-only, so it fails. Use Distrobox for packages.
• Copying a program into /usr (for example with sudo install … /usr/… or make install). /usr is read-only.
• Installing into /opt. It is writable, but emptied on every boot.
• Changing the image for one program. Anything that must be part of the system comes with a new version of the image.

Services

d77void Immutable uses runit, like Void Linux. There is no systemd: systemctl and journalctl do not exist. The general runit documentation in the Void Linux Handbook applies; this page covers what is specific here.

Where services are

/var/service leads to /etc/runit/runsvdir/default, so enabling or disabling a service is a change to /etc, and is kept across restarts and updates like any other. See What is kept.

Only services whose programs are part of the image can be used: there is no package manager to add new ones. Programs in a Distrobox container are not system services.

Everyday commands

The state of every enabled service:

sudo sv status /var/service/*

Restart, stop or start one (until the next boot):

sudo sv restart NetworkManager
sudo sv down bluetoothd
sudo sv up bluetoothd

Enable a service that is in the image but not enabled, permanently:

sudo ln -s /etc/sv/<name> /var/service/

Disable one permanently:

sudo rm /var/service/<name>

A service the image enables and you disabled shows up in d77-etc-diff as deleted runit/runsvdir/default/<name>. To enable it again, create the link as above.

Services enabled by default

To stop the system from updating, do not disable d77-update: set POLICY=disabled (or check) as described in Update settings.

Logs

d77void’s own services keep their logs in /var/log/<name>/current, with times in UTC:

sudo tail -n 20 /var/log/d77-update/current
sudo tail -n 20 /var/log/d77-boot-ok/current
sudo tail -n 20 /var/log/d77-firstboot-flatpak/current

Kernel messages:

sudo dmesg | tail -n 50

Your own service

A service of your own is a folder in /etc/sv with an executable run script that starts the program in the foreground. It is kept like the rest of /etc. Its program must be somewhere that survives a restart (your home, or the script itself), never /opt or /usr.

sudo mkdir /etc/sv/my-service
sudo nano /etc/sv/my-service/run
sudo chmod +x /etc/sv/my-service/run
sudo ln -s /etc/sv/my-service /var/service/

A minimal run script:

#!/bin/sh
exec 2>&1
exec /home/<you>/bin/my-program

Common problems

Problems seen on real installations, with what causes them and what to do.

The update download is very slow, or keeps stopping

Updates are about 3 GB and come from SourceForge, which often serves them at a few hundred KB/s and sometimes drops long connections (Connection reset by peer in the update log).

Nothing needs to be done: the download continues from where it stopped, by itself. It retries for about 5 minutes and, if the connection is still down, tries again 30 minutes later. Switching the computer off is fine too; the next boot continues the same download.

A wired connection helps. While a download is running, the computer does not go to sleep on its own.

To watch it, see step 5 of Checking an update.

No “Update ready” notice appeared

• The first look of each boot waits 10 minutes, then every 6 hours. A download then takes a while.
• The notice is shown once per session and stays until you close it. If it was closed, cat /run/d77/update-ready still shows the waiting version.
• With POLICY=check, the notice is “Update available” instead, and nothing is downloaded until you run sudo d77-update stage --now.
• Nothing is downloaded while the previous version is running; see below.

Checking an update shows where things stand.

Another operating system starts instead of d77void (UEFI)

d77void installs its boot loader in the standard place every UEFI firmware can start (EFI/BOOT/BOOTX64.EFI), without adding an entry of its own to the firmware’s boot list. If another system was installed before, its entry may still come first.

Change the boot order in the firmware setup (or pick the disk from the firmware’s boot menu), and remove the old system’s entry if that system is gone. Seen on a NovaCustom NV41 with Dasharo.

The previous version starts without being chosen

Seen on a Lenovo T480s with Libreboot: when the firmware’s SeaBIOS did not find the disk, the computer was started through the GRUB built into Libreboot, which then loaded d77void’s menu. That menu could not read its own settings in that case and started slot A, which was the previous version.

Fixed in versions published from 18 October 2026 on; existing installations are fixed by the first such version once it has been confirmed. Those versions also show “Previous version in use” whenever the running slot is not the confirmed one. See Recovery.

xbps-install fails

Expected: the system’s files and package database are read-only. Install the program with Flatpak or inside a Distrobox container; see Where to install applications.

A program copied into /usr or /opt does not work or disappears

/usr is read-only and /opt is emptied on every boot. Keep your own programs in your home, or use Flatpak, Distrobox or an AppImage.

A change to a file in /etc did not stick

Changes to /etc are kept. If one seems lost:

1. Check that the editor really saved the file. In vi/vim, :wq saves and quits; :q! quits without saving.
2. Run d77-etc-diff: a file you changed is listed as changed. If it is not listed, the change was not saved, or it was identical to the image’s.

Seen on a Librebox LT1000: a line added to /etc/fstab with vi was missing after a restart; the file had never been saved. Writing it again kept it.

Firefox is not installed

Firefox comes from Flathub and is installed on the first boot with a network connection, in the background, a few minutes after the desktop appears. Without a network it tries again every minute.

sudo tail -n 20 /var/log/d77-firstboot-flatpak/current

distrobox stop hangs

On a system without systemd, a container that shares the system’s processes cannot be stopped cleanly. d77void Immutable creates every new container with its own processes, which avoids this. A container created elsewhere, or with an old configuration, can be recreated with --unshare-process; see Distrobox.

Reporting a problem

Include:

• the running version: grep IMAGE_VERSION /etc/os-release;
• the machine and its firmware (UEFI, Legacy BIOS, coreboot, Libreboot);
• the outputs of steps 2, 3 and 7 of Checking an update if it is about updates or booting;
• what you did, what you expected, and what happened.