OS profiles and snapshots

This page explains OS profiles and snapshots in Flipper OS, how to use them, and how to manage them using CLI helper tools.

When a Linux device is used as a multitool, in roles like a Wi-Fi router, a media box, and a desktop, it gradually accumulates installed packages, modified config files, and saved data. Eventually, the system becomes too messy to use, and the only solution is to reinstall it from scratch. With a multitool, users often need to switch between setups, save a working state before experimenting, and roll back after breaking things.

Flipper OS introduces the concept of OS profiles. An OS profile is an isolated system you can boot into and use: install new packages with apt, change config files, and do whatever you want with it.

Flipper One has several OS profiles specialized for different roles, such as Desktop, TV media box, or Router — and you can add more. You can select OS profiles in the boot menu:

A profile contains a Linux kernel and a / root directory including the desktop environment, installed packages, and configuration files. However, several directories are shared between all profiles:

Shared directories allow you to preserve logs and exchange files between OS profiles. For example, you can reboot Flipper One into desktop mode to study logs produced in router mode. Switching profiles changes how the system behaves without touching /home, and a deleted or broken profile cannot affect any of the shared volumes.

Internally, Flipper OS uses Btrfs to implement the functionality of OS profiles, snapshots, the common boot menu, and shared directories.

While you work in an OS profile, you can save its state in a read-only copy called a snapshot. For example, you can make a snapshot as a save point before a risky change. If something goes wrong, you can always restore a profile to a working state. You can also save a successful configuration in a snapshot, and then create new profiles from it.

Snapshots are not bootable and do not appear in the boot menu. It usually takes a few seconds to create an OS profile from a snapshot. You don't need to use an external SD card or wait for the system to install.

Stock snapshots are a special type of snapshot preloaded on Flipper One and used to initialize starting OS profiles. New versions of stock snapshots can be downloaded from an update server. You can use stock snapshots to create new OS profiles.

Stock snapshot names match initial OS profile names:

However, you can rename profiles, create new ones or delete those you don't need.

Flipper OS uses Btrfs, which is a copy-on-write (CoW) file system. When you create a snapshot or a new profile, no data is duplicated on disk, so no extra space is consumed. When you make changes in a profile, only the changed blocks are written anew, and everything else is shared between the original and the copy. This means you can keep multiple profiles and snapshots without using proportionally more disk space.

You can create snapshots, add new profiles, and do other things using the command line interface (CLI) from any Flipper OS profile. The CLI commands are included in the Flipper OS distribution and instantly available on Flipper One.

CLI commands are preinstalled system-wide, and you can run them from any directory. All commands need administrator rights, so you need to start each with sudo. The first time you use sudo in a session, it asks for your password, which is normal.

Rule of thumb: always make a snapshot before you experiment, and keep a _stock around as your always-safe fallback.

Each CLI command accepts the -h (--help) flag for a quick reminder of what it does; for example, create-profile -h.

Use list-profiles to view existing OS profiles, the currently booted profile, and the profile inheritance:

Shows the profile list, which one is currently booted, and which are built-in (stock).

You can make a snapshot as a save point before making an important change or a risky action. The create-snapshot command demonstrated below creates a snapshot based on your currently booted profile:

You can specify the snapshot label:

The create-profile command takes a snapshot and turns it into a bootable profile @MyDesktop. This is how you "go back" to a saved state.

Shows every saved snapshot and which profile it came from.

You can make a new profile from a stock profile using create-profile:

The command above creates a fresh, bootable @DesktopTest from the @Desktop_stock profile. You can now reboot and pick @DesktopTest from the boot menu.

You can also make a new profile straight from your currently booted profile (including all your changes):

Creates @DesktopTest2 as a copy of Desktop as it is right now.

The rename-profile command renames the profile and updates its boot menu entry. Profile content stays unchanged. You cannot rename the profile you are currently booted into, so boot into another one first.

Profiles and snapshots share most of their data, so they take far less room than the sizes suggest. The columns:

Add -q (sudo btrfs-show-space -q) for a faster run that skips the REFERENCED column.

Use delete-profile to delete a profile and remove it from the boot menu:

Use delete-snapshot to delete a snapshot you no longer need:

Each command asks for a y/N confirmation first, so a typo won't wipe anything by accident. You will need to confirm twice to delete a read-only target, and three times to delete a stock snapshot.

btrfs-maintenance runs housekeeping across all your profiles and snapshots. For everyday maintenance, use the all parameter:

This command does three actions in the following order:

You can also run any action on its own: sudo btrfs-maintenance check, dedup, or balance. There is also the fix action, a scrub that repairs damage where a good copy exists. The full btrfs-maintenance all call can take a while on a busy disk, so it's best to run it when you don't need the device urgently.

The create-profile -m command moves the snapshot into the new profile instead of copying it: the snapshot is consumed (gone afterward), but its parent link is kept. Most people don't need this. It's mainly useful for incremental backup transfers (see below). If in doubt, use the normal copy above.

You can keep your profiles and snapshots backed up off the device:

Back up a profile to a USB stick (a read-write profile is snapshotted read-only for you first, and that restore point is kept):

Restore it later, on this or another Flipper One:

The restored copy lands under @snapshots as read-only; turn it into a bootable profile with create-profile.

For backup chains you can send only what changed since a previous backup with -i (against the profile's _stock base) or -p PARENT (against a specific earlier snapshot). Incremental restores need that parent to already exist on the receiving device.

Each profile's root is a separate subvolume mounted to the filesystem root (/). A special boot subvolume mounted to /boot contains Linux kernels and boot configuration for all profiles. The /boot directory is also shared; however, there is an isolated kernel for each OS profile.