Debian COSMIC: A Fast-Track System Extension & Monorepo Packaging Journey

System76’s COSMIC Desktop Environment—written from the ground up in Rust—is one of the most exciting developments in the Linux desktop ecosystem. Built for modern Wayland composition, modularity, and high-performance UX, it has captured the attention of desktop enthusiasts across distributions.

However, for users running Debian Testing or Debian Unstable, getting COSMIC onto their machines traditionally presents a steep hill to climb. The official upstream codebase consists of dozens of independent repositories (cosmic-comp, cosmic-panel, cosmic-applets, cosmic-settings, cosmic-files, and more) along with hundreds of Rust crate dependencies. Packaging each component individually according to strict Debian policy involves filing dozens of ITPs, waiting through NEW queue processing, and managing endless dependency updates.

For someone who simply wants to explore, test, and run COSMIC on Debian today, waiting for full distribution packaging is impractical.

To bridge this gap, we created Debian COSMIC (debian-cosmic)—a pragmatic, fast-track delivery pipeline designed to build, package, and run COSMIC Epoch on Debian Testing and Sid right now.

The Fast-Track Pivot: The Monorepo Strategy

Rather than fighting distribution policy or attempting to maintain fifty separate Debian source packages, we leveraged System76’s official cosmic-epoch monorepo releases (e.g. epoch-1.4.0).

By compiling the monorepo in an isolated, sanitized Debian Testing container/chroot, we build the entire COSMIC stack—compositor, panel, settings, launcher, applets, and session helpers—in a single, automated pass.

This approach gives us two primary delivery outcomes:

1. The Monorepo .deb (cosmic-epoch-monorepo.deb)

For users who prefer standard Debian package management:

• A single, unified .deb package containing the entire compiled /usr hierarchy of the COSMIC desktop environment.
• Automatically versioned against upstream release tags (e.g. 1.4.0-1) and published to our APT repository and GitHub Releases.
• Easily installed via standard apt install:

  sudo apt update
  sudo apt install cosmic-epoch-monorepo
  

2. The System Extension (systemd-sysext) Overlay

For users who embrace an immutable host philosophy or don’t want external packages mutating their pristine host /usr filesystem:

• We package the compiled COSMIC stack into an OCI container image delivered via the GitHub Container Registry (ghcr.io).
• Using systemd-sysext, the image is mounted at runtime as a read-only overlay on top of /usr.
• When you log into COSMIC, the desktop environment is dynamically merged into your host. When you switch back to GNOME or KDE, a simple helper script (cosmic-toggle) unmerges the overlay, leaving your host filesystem 100% clean and untouched.

🛡️ Preventing ABI Drift: The cosmic-canary Package

Running a systemd-sysext overlay on a rolling distribution like Debian Testing or Sid introduces a subtle technical challenge: host library ABI drift.

Because the sysext binaries link dynamically against shared C libraries on your host (such as Mesa graphics drivers, DRM, Vulkan, or Pipewire), a routine apt upgrade on your host might update libgbm1 or libdrm2 to a newer version. If the new host library introduces an ABI change, launching COSMIC from an older sysext overlay can cause black screens, broken rendering, or segfaults.

To solve this without cluttering standard Debian packaging, we created an “Early Warning System”: the JIT Canary (cosmic-canary) package.

The Tiered Dependency Model

Generated dynamically at build time using equivs-build (via our generate-cosmic-canary.sh tool), the cosmic-canary package pins your host’s libraries into two distinct zones:

• 🔴 The Strict Zone (= dependency): Pinned to the exact version used at build time for volatile graphics and hardware stack components (libmesa, libgbm, libdrm, libvulkan, libdisplay-info, libpixman, libxkbcommon, libinput, libpipewire). If a host apt upgrade attempts to bump Mesa or DRM versions, cosmic-canary blocks the upgrade, alerting you that a sysext rebuild is required before upgrading your host drivers.
• 🟢 The Relaxed Zone (>= dependency): Pinned with minimum version bounds for stable system layers and protocol libraries (libc6, libgcc, libstdc++, libwayland, libdbus, libpam, libglib, libssl, libx11). Security updates and minor patches to these libraries are allowed through without triggering false alarms.

Quickstart: How to Try Debian COSMIC

Whether you want the unified .deb or the sysext overlay, setting up Debian COSMIC takes only a few minutes.

Method A: APT Repository (.deb)

# 1. Add the GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://rickysarraf.github.io/debian-cosmic/debian-cosmic.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/debian-cosmic.gpg

# 2. Add the repository
echo "deb [signed-by=/etc/apt/keyrings/debian-cosmic.gpg] https://rickysarraf.github.io/debian-cosmic/ unstable main" | sudo tee /etc/apt/sources.list.d/debian-cosmic.list

# 3. Install COSMIC Monorepo
sudo apt update
sudo apt install cosmic-epoch-monorepo

Method B: System Extension (sysext)

If you have systemd >= 248 and Docker installed:

1. Clone the debian-cosmic repository:

   git clone https://github.com/rickysarraf/debian-cosmic.git
   cd debian-cosmic
   

2. Pull and stage the latest sysext overlay:

   ./bin/cosmic-update
   

3. Toggle the COSMIC environment on/off whenever you want:

   ./bin/cosmic-toggle
   

Conclusion

debian-cosmic is not intended to replace official, long-term Debian packaging efforts. Instead, it is a fast-track, hacker-friendly playground for early adopters, developers, and testers who want to experience System76’s COSMIC Epoch on Debian Testing and Sid right now.

By combining monorepo container builds, systemd-sysext overlays, and cosmic-canary ABI safety checks, we have achieved a fast, clean, and reliable way to run cutting-edge desktop software on Debian without sacrificing system stability.

Check out the debian-cosmic repository on GitHub to contribute, report issues, or try out the latest build!