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 introduction 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 os profiles 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 boot menu displays available os profiles desktop, tv media box, router, and others 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 /home — user home directories /var/log — logs /var/cache — application cache 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 https //btrfs readthedocs io/en/latest/ to implement the functionality of os profiles, snapshots, the common boot menu, and shared directories snapshots 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 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 os profiles and snapshots lifecycle jpg stock snapshot names match initial os profile names desktop stock → desktop router stock → router tv media box stock → tv media box no graphics stock → no graphics minimal stock → minimal however, you can rename profiles, create new ones or delete those you don't need profile snapshot stock large png disk space usage flipper os uses btrfs https //btrfs readthedocs io/en/latest/ , 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 see the actual space usage with btrfs show space the btrfs show space command shows the real footprint the unique column tells you how much exclusive data each entry holds, and the referenced column shows its total logical size including shared blocks $ sudo btrfs show space \== filesystem == overall device size 59 50gib device allocated 3 49gib device unallocated 56 01gib device missing 0 00b device slack 0 00b used 2 42gib free (estimated) 56 86gib (min 28 85gib) free (statfs, df) 56 86gib data ratio 1 00 metadata ratio 2 00 global reserve 7 75mib (used 0 00b) multiple profiles no data metadata system id path single dup dup unallocated total slack \ 1 /dev/sda2 2 98gib 512 00mib 16 00mib 56 01gib 59 50gib \ total 2 98gib 256 00mib 8 00mib 56 01gib 59 50gib 0 00b used 2 12gib 153 33mib 16 00kib measuring 12 subvolume(s) (du + compsize), please wait \== root subvolumes & snapshots == name unique referenced total @snapshots/@desktop 2026 07 14 10 15 16 0 0b 2 0gib 3 4gib @snapshots/@desktop 2026 07 14 10 16 37 desktop before changes 0 0b 2 0gib 3 4gib @desktop 4 0kib 2 0gib 3 4gib < booted @desktop stock 76 0kib 2 0gib 3 4gib @minimal 0 0b 1 4gib 2 4gib @minimal stock 0 0b 1 4gib 2 4gib @no graphics 0 0b 1 4gib 2 4gib @no graphics stock 0 0b 1 4gib 2 4gib @router 0 0b 1 4gib 2 4gib @router stock 0 0b 1 4gib 2 4gib @tv media box 0 0b 1 5gib 2 5gib @tv media box stock 0 0b 1 5gib 2 5gib unique = freed if you delete that subvolume alone (uncompressed) referenced = real on disk size, compressed; counts shared extents, so not additive total = apparent (uncompressed) profile and snapshot cli 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 cli command quick reference i want to command list existing profiles sudo list profiles list existing snapshots sudo list snapshots see space used per profile/snapshot sudo btrfs show space save a restore point sudo create snapshot \[name] create a profile from a stock snapshot sudo create profile @x stock @new create a profile from the current profile sudo create profile @x @new restore a profile from a snapshot sudo create profile @snapshots/ @new rename a profile sudo rename profile @old @new delete a profile sudo delete profile @name delete a snapshot sudo delete snapshot @snapshots/ back up to a file or usb sudo send snapshot @x /path/or/dir restore a backup file sudo receive snapshot \<file> maintain the disk health sudo btrfs maintenance all 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 list existing profiles use list profiles to view existing os profiles, the currently booted profile, and the profile inheritance $ sudo list profiles booted profile @desktop (id 265) name kind id created ro parent @desktop profile 265 2026 07 03 12 14 21 rw @desktop stock (264) < booted @desktop stock stock 264 2026 07 03 12 10 22 ro @minimal stock (262) @minimal profile 263 2026 07 03 12 10 22 rw @minimal stock (262) @minimal stock stock 262 2026 07 03 12 10 22 ro @router profile 269 2026 07 03 12 14 55 rw @router stock (268) @router stock stock 268 2026 07 03 12 14 54 ro @minimal stock (262) @tv media box profile 267 2026 07 03 12 14 54 rw @tv media box stock (266) @tv media box stock stock 266 2026 07 03 12 14 21 ro @minimal stock (262) shows the profile list, which one is currently booted, and which are built in (stock) make a snapshot as a save point 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 $ sudo create snapshot created @snapshots/@desktop 2026 07 03 14 02 25 (read only) you can specify the snapshot label $ sudo create snapshot test created @snapshots/@desktop 2026 07 03 14 02 22 test (read only) restore a profile from a snapshot 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 $ sudo create profile @snapshots/@desktop 2026 07 03 14 02 22 test @mydesktop create bootable profile "@mydesktop" with a writable copy of @snapshots/@desktop 2026 07 03 14 02 22 test on /dev/sda2? \[y/n] y flipper bls wrote entry for @mydesktop (kernel 7 1 0 g5f8b21274ff4, slot 92) profile '@mydesktop' created from '@snapshots/@desktop 2026 07 03 14 02 22 test' (writable, boot entry added) reboot and pick '@mydesktop' from the boot menu to use it list existing snapshots $ sudo list snapshots name id created parent @snapshots/@desktop 2026 07 03 14 02 22 test 272 2026 07 03 14 02 22 @desktop (265) @snapshots/@desktop 2026 07 03 14 02 25 273 2026 07 03 14 02 25 @desktop (265) shows every saved snapshot and which profile it came from make a new profile from a stock snapshot you can make a new profile from a stock profile using create profile $ sudo create profile @desktop stock @desktoptest create bootable profile "@desktoptest" with a writable copy of @desktop stock on /dev/sda2? \[y/n] y flipper bls wrote entry for @desktoptest (kernel 7 1 0 g5f8b21274ff4, slot 92) profile '@desktoptest' created from '@desktop stock' (writable, boot entry added) reboot and pick '@desktoptest' from the boot menu to use it the command above creates a fresh, bootable @desktoptest from the @desktop stock profile you can now reboot and pick @desktoptest from the boot menu make a new profile from the booted profile you can also make a new profile straight from your currently booted profile (including all your changes) $ sudo create profile @desktop @desktoptest2 create bootable profile "@desktoptest2" with a writable copy of @desktop on /dev/sda2? \[y/n] y flipper bls wrote entry for @desktoptest2 (kernel 7 1 0 g5f8b21274ff4, slot 92) profile '@desktoptest2' created from '@desktop' (writable, boot entry added) reboot and pick '@desktoptest2' from the boot menu to use it creates @desktoptest2 as a copy of desktop as it is right now rename a profile 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 $ sudo rename profile @desktoptest @playground renamed @desktoptest > @playground flipper bls reissued boot entry for @playground view disk space used by profiles and snapshots $ sudo btrfs show space filesystem 28 00gib, used 6 42gib (22%) name unique referenced total @desktop 412 0mib 3 10gib 4 85gib < booted @desktop stock 0 0b 2 98gib 4 61gib @minimal 8 0mib 1 42gib 1 90gib @minimal stock 0 0b 1 41gib 1 88gib profiles and snapshots share most of their data, so they take far less room than the sizes suggest the columns unique data only this one holds this is roughly what you get back if you delete just this one and keep the rest referenced its real on disk size (compressed) because data is shared, these don't add up across rows total the apparent, uncompressed size add q ( sudo btrfs show space q ) for a faster run that skips the referenced column delete a profile or snapshot use delete profile to delete a profile and remove it from the boot menu \# sudo delete profile @desktoptest2 delete profile '@desktoptest2'? \[y/n] y deleted @desktoptest2 removed boot entry /boot/loader/entries/92 desktoptest2 flipperos desktoptest2 7 1 0 g5f8b21274ff4 conf use delete snapshot to delete a snapshot you no longer need $ sudo delete snapshot @snapshots/@desktop 2026 07 03 14 08 44 minimal deleteme delete restore point snapshot '@snapshots/@desktop 2026 07 03 14 08 44 minimal deleteme'? \[y/n] y deleted @snapshots/@desktop 2026 07 03 14 08 44 minimal deleteme 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 maintain the disk health btrfs maintenance runs housekeeping across all your profiles and snapshots for everyday maintenance, use the all parameter sudo btrfs maintenance all this command does three actions in the following order check a read only scrub that verifies every checksum (finds silent corruption, changes nothing) dedup reclaims space by sharing identical data between profiles and snapshots balance tidies partly empty storage chunks so free space is usable again 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 advanced "move" a snapshot into a profile 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 $ sudo create profile m @snapshots/@desktop 2026 07 03 14 02 22 test @mydesktop2 create bootable profile "@mydesktop2" by moving @snapshots/@desktop 2026 07 03 14 02 22 test into it (source consumed, parent preserved) on /dev/sda2? \[y/n] y flipper bls wrote entry for @mydesktop2 (kernel 7 1 0 g5f8b21274ff4, slot 92) profile '@mydesktop2' moved from '@snapshots/@desktop 2026 07 03 14 02 22 test' (writable, boot entry added) reboot and pick '@mydesktop2' from the boot menu to use it (source consumed; parent uuid preserved) advanced back up and restore profile to a file or usb you can keep your profiles and snapshots backed up off the device the send snapshot command writes a profile or snapshot out to a file (or a folder, or straight over ssh ) the receive snapshot command reads a profile or snapshot back in 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) sudo send snapshot @desktop /mnt/usb/ restore it later, on this or another flipper one sudo receive snapshot /mnt/usb/desktop 2026 07 03 14 02 22 pack zst 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 explanation subvolume mounting 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 see the mounted subvolume details using /etc/fstab uuid=… / btrfs defaults,compress=zstd,noatime,ssd,discard=async,x systemd growfs 0 0 uuid=… /boot btrfs compress=zstd,noatime,ssd,discard=async,subvol=boot 0 0 uuid=… /home btrfs compress=zstd,noatime,ssd,discard=async,subvol=@home 0 0 uuid=… /var/log btrfs compress=zstd,noatime,ssd,discard=async,subvol=@var log 0 0 uuid=… /var/cache btrfs compress=zstd,noatime,ssd,discard=async,subvol=@var cache 0 0 see the list of btrfs subvolumes using btrfs subvol list $ sudo btrfs subvol list / id 256 gen 97 top level 5 path @minimal stock id 257 gen 132 top level 5 path boot id 258 gen 137 top level 5 path @home id 259 gen 115 top level 5 path @snapshots id 260 gen 150 top level 5 path @var log id 261 gen 121 top level 5 path @var cache id 262 gen 145 top level 5 path @minimal id 263 gen 86 top level 5 path @desktop stock id 265 gen 93 top level 5 path @tv media box stock id 266 gen 146 top level 5 path @tv media box id 267 gen 96 top level 5 path @router stock id 268 gen 146 top level 5 path @router id 269 gen 99 top level 5 path @no graphics stock id 270 gen 145 top level 5 path @no graphics id 271 gen 112 top level 259 path @snapshots/@desktop 2026 07 14 10 15 16 id 272 gen 114 top level 259 path @snapshots/@desktop 2026 07 14 10 16 37 desktop before changes id 273 gen 150 top level 5 path @desktop