PlayOS Partition Layout

Version: 1.0 Applies to: Sprint 10+ installer-deployed internal disks and Sprint 6+ live USB media.

This document is the authoritative reference for on-disk partitioning. The layout is different for the removable live-USB image and the internal NVMe install target; the installer (playos-installer) creates the internal layout, while scripts/gen-ally-usb-image.sh and scripts/gen-installer-usb-image.sh create the USB layouts.

1. Internal disk (installed system)

The installer writes a GPT table with five partitions to the target fixed disk (the non-USB NVMe/SATA drive):

#LabelSizeFilesystemPurpose
1ESP512 MiBFAT32EFI System Partition; EFI/BOOT/BOOTX64.EFI
2playos-a4 GiBsquashfs (read-only)Active system slot
3playos-b4 GiBsquashfs (read-only)Inactive system slot (A/B updates, Sprint 11.5)
4misc64 MiBext4A/B slot metadata (/data/misc-style state)
5playos-dataremainderext4Writable user data
GPT disk (internal NVMe/SATA)
├── Partition 1: ESP           512 MiB  FAT32     label "ESP"
├── Partition 2: playos-a      4 GiB    squashfs  label "playos-a"   (active slot)
├── Partition 3: playos-b      4 GiB    squashfs  label "playos-b"   (inactive slot)
├── Partition 4: misc          64 MiB   ext4      label "misc"       (A/B metadata)
└── Partition 5: playos-data   remainder ext4     label "playos-data" (writable)

Rules:

  • playos-a and playos-b are immutable system slots. misc carries the tiny A/B slot state (which slot is booted / healthy); it is formatted ext4 for convenience.
  • playos-data holds all user content: games, saves, cache, log, updates, config.
  • The installer never silently formats a disk; the user must explicitly confirm the target with a hold-to-confirm gesture.
  • Sprint 10 creates the slots; A/B update/rollback landed in Sprint 11/11.5; dm-verity remains planned (Sprint 12+).

2. Live USB (normal system image)

make ally-usb-image produces output/ally/images/playos-ally-usb.img with a compact three-partition GPT layout:

#LabelSizeFilesystemPurpose
1ESP256 MiBFAT32EFI System Partition; EFI/BOOT/BOOTX64.EFI
2playos-a2048 MiBext2System image (EFI stub kernel lives on ESP)
3playos-dataremainderext4Writable scratch / diagnostics

This layout is intentionally simpler than the internal layout: the live image boots entirely from its EFI-stub kernel with an embedded initramfs, and playos-a exists as a labelled system container rather than as a booted root.

3. Installer USB

make installer-image produces output/installer/images/playos-ally-installer.img. It reuses the three-partition live-USB geometry but carries a payload partition:

#LabelSizeFilesystemPurpose
1ESP256 MiBFAT32Installer kernel (playos.mode=install) as EFI/BOOT/BOOTX64.EFI
2playos-a2048 MiBext2Install payload: /rootfs.squashfs + /BOOTX64.EFI
3playos-dataremainderext4Scratch / preserved diagnostics

The installer kernel boots the one-shot installer UI. It mounts its own playos-a read-only and streams rootfs.squashfs into the target playos-a slot, and copies /BOOTX64.EFI (the normal production kernel) into the target ESP.

4. Data partition contents

The writable playos-data partition is provisioned on first boot to:

/data/
    games/<game-id>/          manifest.json, bin/, assets/, shaders/, licenses/
    saves/<game-id>/          profiles/, autosaves/, settings/
    cache/<game-id>/          shaders/, compiled-assets/, temporary/
    resources/
    downloads/
    log/
    updates/
    screenshots/
    config/
    profiles/

A .playos-storage-version marker is stamped at the root after first-boot provisioning; its presence/absence drives first-boot seeding of shipped games.

Related: Installation Guide, System Architecture