COSMIC Desktop Environment

COSMIC is a modern, configurable, and lightweight Wayland desktop environment developed by System76. It is designed to be fast, efficient and user-friendly while maintaining a professional appearance. As of April 2025, COSMIC’s latest release is Alpha 7, with a beta release planned in the coming months.

Enabling COSMIC in Ghaf

COSMIC is the default desktop environment in Ghaf. If you wish to explicitly configure or customize the desktop environment, you can still set it manually in your graphics configuration:

profiles.graphics.compositor = "cosmic";

This configuration sets COSMIC as the active desktop environment for Ghaf.

Note

Starting from April 2025, COSMIC DE is fully integrated into NixOS options, and its tools are included in nixpkgs. Prior to this, COSMIC had to be added to Ghaf from the external flake nixos-cosmic.

Configuration Components

COSMIC’s configuration in Ghaf consists of several key components:

1. Core COSMIC DE Configuration

COSMIC handles its configuration via simple Rust Object Notation (RON) files located in the user’s home directory under .config/cosmic.

In the Ghaf Nix configuration, however, we have introduced a conversion mechanism where the entire directory tree is represented by a single YAML file (cosmic.config.yaml). This YAML file acts as the system default COSMIC configuration and is applied to all fresh installations of Ghaf.

If the user makes manual changes to the configuration while using Ghaf, those changes will take precedence over the system defaults.

Note

The ghaf.graphics.cosmic.renderDevice Nix option allows manual specification of the rendering device used by COSMIC, by providing a device path (e.g., /dev/dri/renderD129). The specified path is assigned to the COSMIC_RENDER_DEVICE environment variable during session startup. This is particularly useful in systems with multiple GPUs or in virtualized environments, where relying on the default device selection may lead to compatibility issues. Setting this option ensures that COSMIC uses the appropriate GPU for rendering.

2. Ghaf COSMIC Nix Configuration

The cosmic.nix module in Ghaf customizes COSMIC to better align with the system’s requirements. Below are the key modifications and adjustments made:

Disabled COSMIC Settings pages

• User Management: The page-users feature in COSMIC settings is disabled.
• Power Settings: The page-power feature is removed, as power management is handled by swayidle and ghaf-powercontrol.
• Sound Settings: The page-sound feature is disabled, with audio control managed by a custom service.
• Network Settings: The page-networking feature is disabled, network settings are configured via the network manager applet.
• Bluetooth Settings: The page-bluetooth feature is disabled, bluetooth settings are configured via the bluetooth applet or the Bluetooth Settings app.

Replacements and Overrides

• Icon Theme: The default COSMIC icon theme is changed to Papirus icon theme.
• GTK Settings: Some default GTK settings are applied to ensure a consistent look and feel.
• Session Management: COSMIC’s session management integrates with ghaf-session.target for better control of Ghaf services.
• Power Management: swayidle replaces cosmic-idle as the default idle and power manager, including configuration for automatic suspend and brightness adjustments.
• Audio Control: A custom Ghaf audio control service works alongside the COSMIC audio applet to provide Ghaf-specific audio control features.

Additional Changes

• DBUS Proxy Integration: Custom DBUS proxy sockets are added for audio, network, and Bluetooth applets.
• Configuration Format: COSMIC’s configuration is centralized into a single YAML file (cosmic.config.yaml) for easier management and deployment. This configuration is installed as an explicit package ghaf-cosmic-config, the derivation of which can be found in cosmic.nix.
• Disabled Services: Several default services, such as geoclue2, pipewire, and gnome-keyring, are explicitly disabled.

These changes ensure that COSMIC in Ghaf is tailored to the system’s specific needs.

3. Panels and Dock

ghaf.graphics.cosmic.panels decides which panels the session has. It defaults to [ "Panel" "Dock" ], which is COSMIC’s usual top panel and bottom dock. An empty list produces a session with neither — the configuration a kiosk product needs, where the panel and dock are a route out of the application the device exists to run.

ghaf.graphics.cosmic.panels = [ ]; # no panel, no dock

The option filters com.system76.CosmicPanel/v1/entries, the key that decides which panels exist at all. It is applied to the selectable panel layouts as well as to the session default, so switching layout cannot restore a panel that was removed. Emptying topPanelApplets or bottomPanelApplets is not a substitute: it leaves two empty bars occupying the screen edges. Conversely, applet options for a panel that is not in panels are a no-op.

The option is build-time only. If you need to toggle panels within a running session, note what was measured on a Dell running cosmic-comp 1.2.0, after source reading gave the wrong answer three times:

• Emptying entries at runtime does remove the panel and dock.
• Restoring entries does not bring them back. cosmic-panel tears the panels down on the config event and never rebuilds them, and logs nothing about it.
• A working revert must also kill cosmic-panel. cosmic-session respawns it through launch-pad with exponential backoff, so allow more than 30 seconds before concluding it has not come back. The fresh process reads the restored entries and rebuilds both panels.
• Per-panel autohide has no effect on this build, whether written at runtime or already present when cosmic-panel starts. It is not a way to hide a panel.
• A file renamed into the config directory is never seen by the watcher: correct on disk, silently never applied. Overrides must be written in place.
• Every file under <component>/v1/ is treated as a config key. A backup left beside one becomes a bogus key whose read failure aborts the entire reload.

4. Keyboard Shortcuts and System Actions

Three options cover the shortcut configuration, and they are separate because COSMIC treats them separately.

ghaf.graphics.cosmic.extraShortcuts appends bindings that spawn a command. Ghaf uses it for the screen recorder, which is its default value when screenRecorder.enable is set.

ghaf.graphics.cosmic.disabledShortcuts names actions, not bindings:

ghaf.graphics.cosmic.disabledShortcuts = [
  "System(AppLibrary)"
  "System(Launcher)"
];

Every binding for a named action is disabled. Naming actions rather than bindings matters because the mapping is not one to one — System(AppLibrary) is bound both to Super+A and to Super on its own, and System(WorkspaceOverview) both to Super+W and to the XF86LaunchA key found on some keyboards. A list of key combinations has to enumerate all of them and silently stops matching when a default changes; naming the action cannot, and an action that no binding uses fails the build.

The bindings are written to com.system76.CosmicSettings.Shortcuts/v1/custom as COSMIC’s Action::Disable. COSMIC applies the user map over the defaults per binding, so bindings that were not named are unaffected.

ghaf.graphics.cosmic.systemActions overrides the commands behind the actions themselves:

ghaf.graphics.cosmic.systemActions = {
  Launcher = "";
  AppLibrary = "";
};

A system action’s value is run as sh -c "<value>", so "" is a genuine no-op. COSMIC merges the system and user maps per key, so unnamed actions keep their values and the override cannot go stale when a later COSMIC adds an action. Naming an action COSMIC does not have fails the build.

Note

The two layers are complementary rather than redundant, and a locked-down product usually wants both: disabledShortcuts covers the bindings shipped today, while systemActions also covers a keyboard with a dedicated key, or a binding a future COSMIC adds. Neither is a single “lock down the desktop” switch, deliberately — disabling Close strands a user who opened a window with no way to shut it, so that call belongs to the product, per binding.

Configuration Files

The main configuration files are located in the modules/desktop/graphics/ directory:

• modules/dektop/graphics - cosmic-config - cosmic-config-to-yaml.sh Helper script to convert .config/cosmic to a YAML config - cosmic.config.yaml Main COSMIC desktop configuration which expands into .config/cosmic - cosmic.nix Main COSMIC Nix configuration

Known Limitations

• COSMIC does not allow forcing Server-Side Decorations for apps running under COSMIC
• COSMIC does not yet support all common Wayland protocols (e.g. zwlr_virtual_pointer_manager_v1, etc.)
• COSMIC is still in relatively early development, with a Beta release planned some time in 2025

For more detailed information about COSMIC’s architecture and features, visit the COSMIC Epoch repository and the System76 COSMIC Epoch homepage.