cosmic-manager

Manage COSMIC desktop declaratively using home-manager.

What is cosmic-manager?

cosmic-manager is a declarative way to manage your COSMIC desktop using home-manager. It provides a set of modules that can be used to configure your favorite desktop environment. This means your settings are easy to backup, share, replicate and restore.

Getting started

Ready to give it a try? Check out the Getting started guide. Once you're done, you can take a look at all of our available options in the Options section.

Found a bug?

Please report it here.

Getting started

cosmic-manager supports both stable Nix and Flakes. So you can choose the one that best fits your needs. Follow the steps below to get started with managing your COSMIC desktop declaratively using cosmic-manager.

Stable Nix

When using stable Nix, you have several options to install cosmic-manager based on your preferences and setup. Choose one of the methods below to get started.

Option 1: Using npins

npins simplifies the process of "pinning" external dependencies for your configuration.

Steps:

  1. Ensure you have followed the npins getting started guide.
  2. Add cosmic-manager to your configuration:
npins add --name cosmic-manager github HeitorAugustoLN cosmic-manager
  1. Update your Nix configuration:

With home-manager integrated into NixOS:

let
  sources = import ./npins;
in
{
  home-manager.users.cosmic-user = {
    imports = [
      (sources.cosmic-manager + "/modules")
    ];

    wayland.desktopManager.cosmic.enable = true;
  };
}

With standalone home-manager:

let
  sources = import ./npins.nix;
in
{
  imports = [
    (sources.cosmic-manager + "/modules")
  ];

  home.username = "cosmic-user";
  programs.home-manager.enable = true;

  wayland.desktopManager.cosmic.enable = true;
}

Option 2: Using Channels

Nix channels offer a simple way to download, update, and use cosmic-manager modules. However, this approach sacrifices reproducibility across different machines.

Steps:

  1. Add the cosmic-manager channel:
sudo nix-channel --add https://github.com/HeitorAugustoLN/cosmic-manager/archive/main.tar.gz cosmic-manager
sudo nix-channel --update
  1. Update your Nix configuration:

With home-manager integrated into NixOS:

{
  home-manager.users.cosmic-user = {
    imports = [
      <cosmic-manager/modules>
    ];

    wayland.desktopManager.cosmic.enable = true;
  };
}

With standalone home-manager:

{
  imports = [
    <cosmic-manager/modules>
  ];

  home.username = "cosmic-user";
  programs.home-manager.enable = true;

  wayland.desktopManager.cosmic.enable = true;
}

Which Option Should I Choose?

  • Use npins: If you want better reproducibility and a cleaner way to manage external dependencies.
  • Use Channels: If you prefer a simpler setup and are okay with sacrificing strict reproducibility.

With either method, you’re set to manage your COSMIC desktop declaratively!

Flakes

Flakes are the preferred way to use cosmic-manager, offering a modern and reproducible way to manage your COSMIC desktop.

If you have Flakes enabled, this will be the easiest and most flexible method to get started.

Adding cosmic-manager as an Input

First, add cosmic-manager to the inputs in your flake.nix file. Here’s an example:

{
  inputs = {
    nixpkgs.url = "nixpkgs/nixos-unstable";
    cosmic-manager = {
      url = "github:HeitorAugustoLN/cosmic-manager";
      inputs = {
        nixpkgs.follows = "nixpkgs";
        home-manager.follows = "home-manager";
      };
    };
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, home-manager, cosmic-manager, ... }: {
    # Outputs will depend on your setup (home-manager as NixOS module or standalone home-manager).
  };
}

Using cosmic-manager with a home-manager as NixOS module installation

If you’re using home-manager as a NixOS module, your flake.nix file might look like this:

{
  outputs = { nixpkgs, home-manager, cosmic-manager, ... }: {
    nixosConfigurations.my-computer = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        home-manager.nixosModules.home-manager
        {
          home-manager.users.cosmic-user = {
            imports = [
              ./home.nix
              cosmic-manager.homeManagerModules.cosmic-manager
            ];
          };
        }
      ];
    };
  };
}

Using cosmic-manager with a standalone home-manager installation

If you’re using home-manager as a standalone tool, your flake.nix file might look like this:

{
  outputs = { nixpkgs, home-manager, cosmic-manager, ... }: {
    homeConfigurations."cosmic-user@my-computer" = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        ./home.nix
        cosmic-manager.homeManagerModules.cosmic-manager
      ];
    };
  };
}

Follow this guide, and you’ll have cosmic-manager up and running with Flakes in no time!

programs.cosmic-term.enable

Whether to enable COSMIC Terminal Emulator.

Type: boolean

Default: false

Example: true

Declared by:

programs.cosmic-term.package

The cosmic-term package to use. Set to null if you don’t want to install the package.

Type: null or package

Default: pkgs.cosmic-term

Declared by:

programs.cosmic-term.colorSchemes

This option has no description.

Type: null or (list of (attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)))

Default: null

Example:

[
  {
    bright = {
      black = "#585B70";
      blue = "#89B4FA";
      cyan = "#94E2D5";
      green = "#A6E3A1";
      magenta = "#F5C2E7";
      red = "#F38BA8";
      white = "#A6ADC8";
      yellow = "#F9E2AF";
    };
    bright_foreground = "#CDD6F4";
    cursor = "#F5E0DC";
    dim = {
      black = "#45475A";
      blue = "#89B4FA";
      cyan = "#94E2D5";
      green = "#A6E3A1";
      magenta = "#F5C2E7";
      red = "#F38BA8";
      white = "#BAC2DE";
      yellow = "#F9E2AF";
    };
    dim_foreground = "#6C7086";
    foreground = "#CDD6F4";
    mode = "dark";
    name = "Catppuccin Mocha";
    normal = {
      black = "#45475A";
      blue = "#89B4FA";
      cyan = "#94E2D5";
      green = "#A6E3A1";
      magenta = "#F5C2E7";
      red = "#F38BA8";
      white = "#BAC2DE";
      yellow = "#F9E2AF";
    };
  }
]

Declared by:

programs.cosmic-term.colorSchemes.*.bright

The bright colors of the terminal.

Type: attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)

Declared by:

programs.cosmic-term.colorSchemes.*.bright.black

The black color of bright colors.

Type: hex color

Example: "#000000"

Declared by:

programs.cosmic-term.colorSchemes.*.bright.blue

The blue color of bright colors.

Type: hex color

Example: "#0000FF"

Declared by:

programs.cosmic-term.colorSchemes.*.bright.cyan

The cyan color of bright colors.

Type: hex color

Example: "#00FFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.bright.green

The green color of bright colors.

Type: hex color

Example: "#00FF00"

Declared by:

programs.cosmic-term.colorSchemes.*.bright.magenta

The magenta color of bright colors.

Type: hex color

Example: "#FF00FF"

Declared by:

programs.cosmic-term.colorSchemes.*.bright.red

The red color of bright colors.

Type: hex color

Example: "#FF0000"

Declared by:

programs.cosmic-term.colorSchemes.*.bright.white

The white color of bright colors.

Type: hex color

Example: "#FFFFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.bright.yellow

The yellow color of bright colors.

Type: hex color

Example: "#FFFF00"

Declared by:

programs.cosmic-term.colorSchemes.*.bright_foreground

The bright foreground color of the terminal.

Type: hex color

Example: "#FFFFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.cursor

The color of the terminal cursor.

Type: hex color

Example: "#FFFFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.dim

The dim colors of the terminal.

Type: attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)

Declared by:

programs.cosmic-term.colorSchemes.*.dim.black

The black color of dim colors.

Type: hex color

Example: "#000000"

Declared by:

programs.cosmic-term.colorSchemes.*.dim.blue

The blue color of dim colors.

Type: hex color

Example: "#0000FF"

Declared by:

programs.cosmic-term.colorSchemes.*.dim.cyan

The cyan color of dim colors.

Type: hex color

Example: "#00FFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.dim.green

The green color of dim colors.

Type: hex color

Example: "#00FF00"

Declared by:

programs.cosmic-term.colorSchemes.*.dim.magenta

The magenta color of dim colors.

Type: hex color

Example: "#FF00FF"

Declared by:

programs.cosmic-term.colorSchemes.*.dim.red

The red color of dim colors.

Type: hex color

Example: "#FF0000"

Declared by:

programs.cosmic-term.colorSchemes.*.dim.white

The white color of dim colors.

Type: hex color

Example: "#FFFFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.dim.yellow

The yellow color of dim colors.

Type: hex color

Example: "#FFFF00"

Declared by:

programs.cosmic-term.colorSchemes.*.dim_foreground

The dim foreground color of the terminal.

Type: hex color

Example: "#FFFFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.foreground

The foreground color of the terminal.

Type: hex color

Example: "#FFFFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.mode

The mode of the colorscheme.

Type: one of “dark”, “light”

Example: "dark"

Declared by:

programs.cosmic-term.colorSchemes.*.name

The name of the colorscheme.

Type: string

Example: "Catppuccin Mocha"

Declared by:

programs.cosmic-term.colorSchemes.*.normal

The normal colors of the terminal.

Type: attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)

Declared by:

programs.cosmic-term.colorSchemes.*.normal.black

The black color of normal colors.

Type: hex color

Example: "#000000"

Declared by:

programs.cosmic-term.colorSchemes.*.normal.blue

The blue color of normal colors.

Type: hex color

Example: "#0000FF"

Declared by:

programs.cosmic-term.colorSchemes.*.normal.cyan

The cyan color of normal colors.

Type: hex color

Example: "#00FFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.normal.green

The green color of normal colors.

Type: hex color

Example: "#00FF00"

Declared by:

programs.cosmic-term.colorSchemes.*.normal.magenta

The magenta color of normal colors.

Type: hex color

Example: "#FF00FF"

Declared by:

programs.cosmic-term.colorSchemes.*.normal.red

The red color of normal colors.

Type: hex color

Example: "#FF0000"

Declared by:

programs.cosmic-term.colorSchemes.*.normal.white

The white color of normal colors.

Type: hex color

Example: "#FFFFFF"

Declared by:

programs.cosmic-term.colorSchemes.*.normal.yellow

The yellow color of normal colors.

Type: hex color

Example: "#FFFF00"

Declared by:

programs.cosmic-term.profiles

The profiles to use in the terminal.

Type: null or (list of (attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)))

Default: null

Example:

[
  {
    command = "bash";
    hold = false;
    is_default = true;
    name = "Default";
    syntax_theme_dark = "COSMIC Dark";
    syntax_theme_light = "COSMIC Light";
    tab_title = "Default";
    working_directory = "/home/user";
  }
  {
    command = "bash";
    hold = false;
    is_default = false;
    name = "New Profile";
    syntax_theme_dark = "Catppuccin Mocha";
    syntax_theme_light = "Catppuccin Latte";
    tab_title = "New Profile";
  }
]

Declared by:

programs.cosmic-term.profiles.*.command

The shell or program to execute when opening a new terminal instance with this profile. If it is not specified, it will default to your system shell.

Type: null or string

Default: null

Example: "bash"

Declared by:

programs.cosmic-term.profiles.*.hold

Whether the terminal should continue running after the command exits.

Type: boolean

Example: true

Declared by:

programs.cosmic-term.profiles.*.is_default

Whether the profile is the default.

Type: boolean

Default: false

Example: true

Declared by:

programs.cosmic-term.profiles.*.name

The name of the profile.

Type: string

Example: "Default"

Declared by:

programs.cosmic-term.profiles.*.syntax_theme_dark

Specifies the color scheme used for syntax highlighting in dark mode for this profile.

Type: string

Example: "COSMIC Dark"

Declared by:

programs.cosmic-term.profiles.*.syntax_theme_light

Specifies the color scheme used for syntax highlighting in light mode for this profile.

Type: string

Example: "COSMIC Light"

Declared by:

programs.cosmic-term.profiles.*.tab_title

Overrides the title of the terminal tab. If it is not specified, it will not override the title.

Type: null or string

Default: null

Example: "Default"

Declared by:

programs.cosmic-term.profiles.*.working_directory

The working directory to use when opening a new terminal instance with this profile. If it is not specified, it will continue using the current working directory.

Type: null or string

Default: null

Example: "/home/user"

Declared by:

programs.cosmic-term.settings

Configuration entries for COSMIC Terminal Emulator.

Type: attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)

Default: { }

Example:

{
  app_theme = {
    __type = "enum";
    variant = "Dark";
  };
  bold_font_weight = 700;
  dim_font_weight = 300;
  focus_follows_mouse = true;
  font_name = "JetBrains Mono";
  font_size = 12;
  font_size_zoom_step_mul_100 = 100;
  font_stretch = 100;
  font_weight = 400;
  opacity = 100;
  show_headerbar = true;
  use_bright_bold = true;
}

Declared by:

programs.cosmic-term.settings.app_theme

Controls the theme of the terminal.

  • Dark: Use the dark theme.
  • Light: Use the light theme.
  • System: Follows the system theme.

Type: null or one of the following RON enum variants: “Dark”, “Light”, “System”

Default: null

Example:

{
  __type = "enum";
  variant = "Dark";
}

Declared by:

programs.cosmic-term.settings.bold_font_weight

Specifies the weight of bold text characters in the terminal.

Type: null or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: null

Example: 700

Declared by:

programs.cosmic-term.settings.dim_font_weight

Specifies the weight of dim text characters in the terminal.

Type: null or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: null

Example: 300

Declared by:

programs.cosmic-term.settings.focus_follows_mouse

Whether to enable focus follows mouse in the terminal.

When enabled, the terminal split will automatically receive focus when the mouse cursor hovers over it, without needing to click.

Type: null or boolean

Default: null

Example: true

Declared by:

programs.cosmic-term.settings.font_name

Specificies the font family to use in the terminal.

Type: null or string

Default: null

Example: "JetBrains Mono"

Declared by:

programs.cosmic-term.settings.font_size

Specifies the font size to use in the terminal.

Type: null or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: null

Example: 12

Declared by:

programs.cosmic-term.settings.font_size_zoom_step_mul_100

Controls the granularity of font size changes when zooming.

Value is multiplied by 0.01 to determine the zoom step (e.g. 100 = 1px).

Type: null or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: null

Example: 100

Declared by:

programs.cosmic-term.settings.font_stretch

Controls the horizontal font spacing of characters in the terminal.

Type: null or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: null

Example: 100

Declared by:

programs.cosmic-term.settings.font_weight

Specifies the weight of normal text characters in the terminal.

Type: null or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: null

Example: 400

Declared by:

programs.cosmic-term.settings.opacity

Specifies the opacity of the terminal background.

Type: null or integer between 0 and 100 (both inclusive)

Default: null

Example: 100

Declared by:

programs.cosmic-term.settings.show_headerbar

Whether to show the terminal window title bar and menu.

Type: null or boolean

Default: null

Example: true

Declared by:

programs.cosmic-term.settings.syntax_theme_dark

Specifies the color scheme used for syntax highlighting in dark mode.

Type: null or string

Default: null

Example: "COSMIC Dark"

Declared by:

programs.cosmic-term.settings.syntax_theme_light

Specifies the color scheme used for syntax highlighting in light mode.

Type: null or string

Default: null

Example: "COSMIC Light"

Declared by:

programs.cosmic-term.settings.use_bright_bold

Whether the terminal should use bright bold text.

Type: null or boolean

Default: null

Example: true

Declared by:

wayland.desktopManager.cosmic.enable

Whether to enable declarative configuration management for the COSMIC Desktop environment.

When enabled, this module allows you to manage your COSMIC Desktop settings through home-manager.

Type: boolean

Default: false

Example: true

Declared by:

wayland.desktopManager.cosmic.configFile

Configuration files for COSMIC components stored in $XDG_CONFIG_HOME.

Each component is identified by its unique identifier (e.g., com.system76.CosmicComp).

Structure for each component:

  • version: Schema version number for the component configuration.
  • entries: Component-specific settings as key-value pairs.

Entry values can be:

  • Simple types: booleans, integers, floating point numbers, strings.

  • Complex types: lists, and attribute sets (RON structs).

  • Special types:

    • raw: The value is stored as-is.
    • optional: The value is stored as an optional value. (e.g. Some(value) or None).
    • char: The value is stored as a single character. (e.g. 'a').
    • map: The value is stored as a map. (e.g. { "key" = "value" }).
    • tuple: The value is stored as a tuple. (e.g. (1, 2, 3)).
    • enum: The value is stored as an enum variant.

  • Named structs: A structured entry with a name identifier.

All values are serialized to RON format using lib.cosmic.generators.toRON.

Type: attribute set of (submodule)

Default: { }

Example:

{
  "com.system76.CosmicComp" = {
    entries = {
      autotile = true;
      autotile_behavior = {
        __type = "enum";
        variant = "PerWorkspace";
      };
      xkb_config = {
        layout = "br";
        model = "";
        options = {
          __type = "optional";
          value = null;
        };
        repeat_delay = 600;
        repeat_rate = 25;
        rules = "";
        variant = "";
      };
    };
    version = 1;
  };
  "com.system76.CosmicSettings" = {
    entries = {
      active-page = "wallpaper";
    };
    version = 1;
  };
  "com.system76.CosmicTerm" = {
    entries = {
      font_name = "JetBrains Mono";
      font_size = 16;
    };
    version = 1;
  };
}

Declared by:

wayland.desktopManager.cosmic.configFile.<name>.entries

Configuration entries for the component.

Type: attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)

Example:

{
  autotile = true;
  autotile_behavior = {
    __type = "enum";
    variant = "PerWorkspace";
  };
}

Declared by:

wayland.desktopManager.cosmic.configFile.<name>.version

Schema version number for the component configuration.

Type: unsigned integer, meaning >=0

Example: 1

Declared by:

wayland.desktopManager.cosmic.dataFile

Data files for COSMIC components stored in $XDG_DATA_HOME.

Each component is identified by its unique identifier (e.g., com.system76.CosmicComp).

Structure for each component:

  • version: Schema version number for the component configuration.
  • entries: Component-specific settings as key-value pairs.

Entry values can be:

  • Simple types: booleans, integers, floating point numbers, strings.

  • Complex types: lists, and attribute sets (RON structs).

  • Special types:

    • raw: The value is stored as-is.
    • optional: The value is stored as an optional value. (e.g. Some(value) or None).
    • char: The value is stored as a single character. (e.g. 'a').
    • map: The value is stored as a map. (e.g. { "key" = "value" }).
    • tuple: The value is stored as a tuple. (e.g. (1, 2, 3)).
    • enum: The value is stored as an enum variant.

  • Named structs: A structured entry with a name identifier.

All values are serialized to RON format using lib.cosmic.generators.toRON.

Type: attribute set of (submodule)

Default: { }

Declared by:

wayland.desktopManager.cosmic.dataFile.<name>.entries

Configuration entries for the component.

Type: attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)

Example:

{
  autotile = true;
  autotile_behavior = {
    __type = "enum";
    variant = "PerWorkspace";
  };
}

Declared by:

wayland.desktopManager.cosmic.dataFile.<name>.version

Schema version number for the component configuration.

Type: unsigned integer, meaning >=0

Example: 1

Declared by:

wayland.desktopManager.cosmic.panels

This option has no description.

Type: null or (list of (attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)))

Default: null

Example:

[
  {
    anchor = {
      __type = "enum";
      variant = "Bottom";
    };
    anchor_gap = true;
    autohide = {
      __type = "optional";
      value = {
        handle_size = 4;
        transition_time = 200;
        wait_time = 1000;
      };
    };
    background = {
      __type = "enum";
      variant = "Dark";
    };
    expand_to_edges = true;
    name = "Panel";
    opacity = 1.0;
    output = {
      __type = "enum";
      value = "Virtual-1";
      variant = "Name";
    };
    plugins_center = {
      __type = "optional";
      value = [
        "com.system76.CosmicAppletTime"
      ];
    };
    plugins_wings = {
      __type = "optional";
      value = {
        __type = "tuple";
        value = [
          [
            "com.system76.CosmicPanelWorkspacesButton"
            "com.system76.CosmicPanelAppButton"
            "com.system76.CosmicAppletWorkspaces"
          ]
          [
            "com.system76.CosmicAppletInputSources"
            "com.system76.CosmicAppletStatusArea"
            "com.system76.CosmicAppletTiling"
            "com.system76.CosmicAppletAudio"
            "com.system76.CosmicAppletNetwork"
            "com.system76.CosmicAppletBattery"
            "com.system76.CosmicAppletNotifications"
            "com.system76.CosmicAppletBluetooth"
            "com.system76.CosmicAppletPower"
          ]
        ];
      };
    };
    size = {
      __type = "enum";
      variant = "M";
    };
  }
]

Declared by:

wayland.desktopManager.cosmic.panels.*.anchor

The position of the panel on the screen.

Type: null or one of the following RON enum variants: “Bottom”, “Left”, “Right”, “Top”

Default: null

Example:

{
  __type = "enum";
  variant = "Bottom";
}

Declared by:

wayland.desktopManager.cosmic.panels.*.anchor_gap

Whether there should be a gap between the panel and the screen edge.

Type: null or boolean

Default: null

Example: true

Declared by:

wayland.desktopManager.cosmic.panels.*.autohide

Whether the panel should autohide and the settings for autohide. If set the value is set to null, the panel will not autohide.

Type: null or (RON optional of (attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)))

Default: null

Example:

{
  __type = "optional";
  value = {
    handle_size = 4;
    transition_time = 200;
    wait_time = 1000;
  };
}

Declared by:

wayland.desktopManager.cosmic.panels.*.autohide.handle_size

The size of the handle in pixels.

Type: null or 32 bit unsigned integer; must be greater than 0

Default: null

Example: 4

Declared by:

wayland.desktopManager.cosmic.panels.*.autohide.transition_time

The time in milliseconds it should take to transition the panel hiding.

Type: 32 bit unsigned integer; between 0 and 4294967295 (both inclusive)

Example: 200

Declared by:

wayland.desktopManager.cosmic.panels.*.autohide.wait_time

The time in milliseconds without pointer focus before the panel hides.

Type: 32 bit unsigned integer; between 0 and 4294967295 (both inclusive)

Example: 1000

Declared by:

wayland.desktopManager.cosmic.panels.*.background

The appearance of the panel.

Type: null or one of the following RON enum variants: “Dark”, “Light”, “ThemeDefault” or RON enum variant “Color” with a list of floating point number value (singular RON tuple enum)

Default: null

Example:

{
  __type = "enum";
  variant = "Dark";
}

Declared by:

wayland.desktopManager.cosmic.panels.*.expand_to_edges

Whether the panel should expand to the edges of the screen.

Type: null or boolean

Default: null

Example: true

Declared by:

wayland.desktopManager.cosmic.panels.*.name

The name of the panel.

Type: string

Example: "Panel"

Declared by:

wayland.desktopManager.cosmic.panels.*.opacity

The opacity of the panel.

Type: null or integer or floating point number between 0 and 1 (both inclusive)

Default: null

Example: 1.0

Declared by:

wayland.desktopManager.cosmic.panels.*.output

The output(s) the panel should be displayed on.

Type: null or one of the following RON enum variants: “Active”, “All” or RON enum variant “Name” with a string value (singular RON tuple enum)

Default: null

Example:

{
  __type = "enum";
  value = "Virtual-1";
  variant = "Name";
}

Declared by:

wayland.desktopManager.cosmic.panels.*.plugins_center

The center plugins of the panel.

Type: null or (RON optional of list of string)

Default: null

Example:

{
  __type = "optional";
  value = [
    "com.system76.CosmicAppletTime"
  ];
}

Declared by:

wayland.desktopManager.cosmic.panels.*.plugins_wings

The plugins that will be displayed on the right and left sides of the panel, respectively.

Type: null or (RON optional of RON tuple of list of string)

Default: null

Example:

{
  __type = "optional";
  value = {
    __type = "tuple";
    value = [
      [
        "com.system76.CosmicPanelWorkspacesButton"
        "com.system76.CosmicPanelAppButton"
        "com.system76.CosmicAppletWorkspaces"
      ]
      [
        "com.system76.CosmicAppletInputSources"
        "com.system76.CosmicAppletStatusArea"
        "com.system76.CosmicAppletTiling"
        "com.system76.CosmicAppletAudio"
        "com.system76.CosmicAppletNetwork"
        "com.system76.CosmicAppletBattery"
        "com.system76.CosmicAppletNotifications"
        "com.system76.CosmicAppletBluetooth"
        "com.system76.CosmicAppletPower"
      ]
    ];
  };
}

Declared by:

wayland.desktopManager.cosmic.panels.*.size

The size of the panel.

Type: null or one of the following RON enum variants: “XS”, “S”, “M”, “L”, “XL”

Default: null

Example:

{
  __type = "enum";
  variant = "M";
}

Declared by:

wayland.desktopManager.cosmic.resetFiles

Whether to enable COSMIC configuration files reset.

When enabled, this option will delete any COSMIC-related files in the specified XDG directories that were not explicitly declared in your configuration. This ensures that your COSMIC desktop environment remains in a clean, known state as defined by your home-manager configuration.

Type: boolean

Default: false

Example: true

Declared by:

wayland.desktopManager.cosmic.resetFilesDirectories

XDG base directories to reset when resetFiles is enabled.

Available directories:

  • config: User configuration ($XDG_CONFIG_HOME)
  • data: Application data ($XDG_DATA_HOME)
  • state: Runtime state ($XDG_STATE_HOME)
  • cache: Cached data ($XDG_CACHE_HOME)
  • runtime: Runtime files ($XDG_RUNTIME_DIR)

Type: list of (one of “config”, “data”, “state”, “cache”, “runtime”)

Default:

[
  "config"
  "state"
]

Example:

[
  "config"
  "data"
  "state"
]

Declared by:

wayland.desktopManager.cosmic.resetFilesExclude

Patterns to exclude from the reset operation when resetFiles is enabled. Supports glob patterns and brace expansion for matching files and directories.

Use this option to preserve specific files or directories from being reset.

Type: list of string

Default: [ ]

Example:

[
  "com.system76.CosmicComp"
  "dev.edfloreshz.CosmicTweaks/v1"
  "com.system76.CosmicSettings/v1/active-page"
  "com.system76.CosmicTerm/v1/{font_size,font_family}"
  "com.system76.{CosmicComp,CosmicPanel.Dock}/v1"
]

Declared by:

wayland.desktopManager.cosmic.stateFile

State files for COSMIC components stored in $XDG_STATE_HOME.

Each component is identified by its unique identifier (e.g., com.system76.CosmicComp).

Structure for each component:

  • version: Schema version number for the component configuration.
  • entries: Component-specific settings as key-value pairs.

Entry values can be:

  • Simple types: booleans, integers, floating point numbers, strings.

  • Complex types: lists, and attribute sets (RON structs).

  • Special types:

    • raw: The value is stored as-is.
    • optional: The value is stored as an optional value. (e.g. Some(value) or None).
    • char: The value is stored as a single character. (e.g. 'a').
    • map: The value is stored as a map. (e.g. { "key" = "value" }).
    • tuple: The value is stored as a tuple. (e.g. (1, 2, 3)).
    • enum: The value is stored as an enum variant.

  • Named structs: A structured entry with a name identifier.

All values are serialized to RON format using lib.cosmic.generators.toRON.

Type: attribute set of (submodule)

Default: { }

Example:

{
  "com.system76.CosmicBackground" = {
    entries = {
      wallpapers = [
        {
          __type = "tuple";
          value = [
            "Virtual-1"
            {
              __type = "enum";
              value = [
                "/usr/share/backgrounds/cosmic/webb-inspired-wallpaper-system76.jpg"
              ];
              variant = "Path";
            }
          ];
        }
      ];
    };
    version = 1;
  };
}

Declared by:

wayland.desktopManager.cosmic.stateFile.<name>.entries

Configuration entries for the component.

Type: attribute set of (null or (attribute set of anything) or boolean or list of anything or signed integer or floating point number or raw RON value or RON char or RON map of anything or RON named struct of anything or RON optional of anything or RON tuple of anything or string)

Example:

{
  autotile = true;
  autotile_behavior = {
    __type = "enum";
    variant = "PerWorkspace";
  };
}

Declared by:

wayland.desktopManager.cosmic.stateFile.<name>.version

Schema version number for the component configuration.

Type: unsigned integer, meaning >=0

Example: 1

Declared by: