rename /cerulean -> /nix

nix/default.nix

@@ -0,0 +1,36 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  mix,
+  inputs,
+  ...
+} @ args:
+mix.newMixture args (mixture: {
+  submods.public = [
+    ./snow
+  ];
+
+  version = "0.2.6-alpha";
+
+  overlays = [
+    # build deploy-rs as a package not from the flake input,
+    # hence we can rely on a nixpkg binary cache.
+    inputs.deploy-rs.overlays.default
+  ];
+
+  nixosModules = rec {
+    default = cerulean;
+    cerulean = ./nixos;
+  };
+})

nix/home/default.nix

@@ -0,0 +1,34 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  username,
+  lib,
+  ...
+}: {
+  # NOTE: you can access the system configuration via the `osConfig` arg
+
+  # WARNING: required for home-manager to work
+  programs.home-manager.enable = true; # user must apply lib.mkForce
+  # Nicely reload systemd units when changing configs
+  systemd.user.startServices = lib.mkDefault "sd-switch";
+
+  home = {
+    username = lib.mkDefault username;
+    homeDirectory = lib.mkDefault "/home/${username}";
+
+    sessionVariables = {
+      NIX_SHELL_PRESERVE_PROMPT = lib.mkDefault 1;
+    };
+  };
+}

nix/nixos/default.nix

@@ -0,0 +1,52 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  root,
+  system,
+  hostname,
+  node,
+  pkgs,
+  lib,
+  _cerulean,
+  ...
+} @ args: {
+  imports =
+    [
+      _cerulean.inputs.sops-nix.nixosModules.sops
+      # _cerulean.inputs.microvm.nixosModules.microvm
+
+      # add support for `options.legacyImports`
+      # ./legacy-imports.nix
+
+      # nixos options declarations
+      (import ./nixpkgs.nix (args // {contextName = "hosts";}))
+
+      # user's nixpkg configuration
+      (import /${root}/nixpkgs.nix)
+    ]
+    # homemanager options declarations
+    ++ (lib.optional (_cerulean.homeManager != null) ./home.nix)
+    # remote deployment configuration
+    ++ (lib.optional (node.deploy.ssh.host != null) ./remote-deploy);
+
+  networking.hostName = lib.mkDefault hostname;
+
+  environment.systemPackages =
+    (with pkgs; [
+      sops
+    ])
+    ++ (with _cerulean.inputs; [
+      deploy-rs.packages.${system}.default
+    ]);
+}

nix/nixos/home.nix

@@ -0,0 +1,82 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  _cerulean,
+  config,
+  root,
+  lib,
+  ...
+} @ args: let
+  inherit
+    (builtins)
+    pathExists
+    ;
+
+  inherit
+    (lib)
+    filterAttrs
+    mapAttrs
+    ;
+in {
+  imports = [
+    _cerulean.homeManager.nixosModules.default
+  ];
+
+  options = {
+    users.users = lib.mkOption {
+      type = lib.types.attrsOf (lib.types.submodule {
+        options.manageHome = lib.mkOption {
+          type = lib.types.bool;
+          default = true;
+          example = false;
+          description = ''
+            Whether Cerulean should automatically enable home-manager for this user,
+            and manage their home configuration declaratively.
+
+            Enabled by default, but can be disabled if necessary.
+          '';
+        };
+      });
+    };
+  };
+
+  config = {
+    home-manager = {
+      useUserPackages = lib.mkDefault false;
+      useGlobalPkgs = lib.mkDefault true;
+
+      overwriteBackup = lib.mkDefault false;
+      backupFileExtension = lib.mkDefault "bak";
+
+      users =
+        config.users.users
+        |> filterAttrs (name: value: value.manageHome && pathExists /${root}/homes/${name})
+        |> mapAttrs (name: _: {...}: {
+          imports = [/${root}/homes/${name}];
+
+          # per-user arguments
+          _module.args.username = name;
+        });
+
+      extraSpecialArgs = _cerulean.specialArgs;
+      sharedModules = [
+        ../home
+
+        (import /${root}/nixpkgs.nix)
+        # options declarations
+        (import ./nixpkgs.nix (args // {contextName = "homes";}))
+      ];
+    };
+  };
+}

nix/nixos/microvm-child.nix

@@ -0,0 +1,13 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

nix/nixos/microvm-parent.nix

@@ -0,0 +1,13 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

nix/nixos/nixpkgs.nix

@@ -0,0 +1,95 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  base,
+  lib,
+  system,
+  config,
+  contextName,
+  ...
+}: let
+  inherit
+    (builtins)
+    mapAttrs
+    ;
+
+  cfg = config.nixpkgs.channels;
+in {
+  options.nixpkgs.channels = lib.mkOption {
+    type = lib.types.attrs;
+    default = {};
+    description = "Declare package repositories";
+    example = {
+      "npkgs" = {
+        source = "inputs.nixpkgs";
+        system = "x86-64-linux";
+        config = {
+          allowUnfree = true;
+          allowBroken = false;
+        };
+      };
+      "upkgs" = {
+        source = "inputs.nixpkgs-unstable";
+        system = "x86-64-linux";
+        config = {
+          allowUnfree = false;
+          allowBroken = true;
+        };
+      };
+    };
+  };
+
+  config = let
+    repos =
+      cfg
+      |> (xs: removeAttrs xs ["base"])
+      |> mapAttrs (
+        name: args:
+          lib.mkForce (
+            assert args ? source
+            || abort ''
+              `nixpkgs.channels.${name}` missing required attribute "source"
+            '';
+              import args.source ({inherit system;} // (removeAttrs args ["source"]))
+          )
+      );
+
+    basePkgs = cfg.base or {};
+  in {
+    # NOTE: _module.args is a special option that allows us to
+    # NOTE: set extend specialArgs from inside the modules.
+    # WARNING: pkgs is a reserved specialArg
+    _module.args = removeAttrs repos ["pkgs" "base"];
+
+    nixpkgs = let
+      nixpkgsConfig = {
+        config = lib.mkForce (basePkgs.config or {});
+        overlays = lib.mkForce (basePkgs.overlays or []);
+      };
+
+      nixpkgsHostsConfig =
+        nixpkgsConfig
+        // {
+          flake.source = lib.mkForce base;
+        };
+
+      nixpkgsHomesConfig = lib.mkIf (!config.home-manager.useGlobalPkgs) nixpkgsConfig;
+    in
+      if contextName == "hosts"
+      then nixpkgsHostsConfig
+      else if contextName == "homes"
+      then nixpkgsHomesConfig
+      else {};
+  };
+}

nix/nixos/remote-deploy/default.nix

@@ -0,0 +1,82 @@
+{
+  config,
+  node,
+  lib,
+  pkgs,
+  hostname,
+  ...
+}: let
+  user = node.deploy.ssh.user;
+  cfg = config.users.users.${user};
+
+  DEFAULT_USER = "cerubld";
+
+  isStandardDeployUser = user == DEFAULT_USER;
+in {
+  assertions = [
+    {
+      assertion = builtins.length node.deploy.ssh.publicKeys != 0;
+      message = ''
+        The Cerulean deployment user `${user}` for node `${hostname}` must have at least
+        one publicKey authorized for ssh deployment! Try setting `nodes.nodes.<name>.deploy.ssh.publicKeys = [ ... ]` <3
+      '';
+    }
+    # {
+    #   assertion = cfg.isSystemUser && !cfg.isNormalUser;
+    #   message = ''
+    #     The Cerulean deployment user `${user}` for node `${hostname}` has been configured incorrectly.
+    #     Ensure `users.users.${user}.isSystemUser == true` and `users.users.${user}.isNormalUser == false`.
+    #   '';
+    # }
+  ];
+
+  warnings = lib.optional (node.deploy.warnNonstandardDeployUser && !isStandardDeployUser) ''
+    The Cerulean deplyment user `${user}` for node `${hostname}` has been overriden.
+    It is recommended to leave this user as `${DEFAULT_USER}` unless you TRULY understand what you are doing!
+    This message can be disabled by setting `<node>.deploy.warnNonstandardBuildUser = false`.
+  '';
+
+  # prefer sudo-rs over sudo
+  security.sudo-rs = {
+    enable = true;
+    wheelNeedsPassword = true;
+
+    # allow the build user to run nix commands
+    extraRules = [
+      {
+        users = [user];
+        runAs = "${node.deploy.user}:ALL";
+        commands = [
+          # "${pkgs.nix}/bin/nix"
+          "ALL" # XXX: WARNING: FIX: TODO: DO NOT FUCKING USE `ALL`
+        ];
+      }
+    ];
+  };
+
+  # XXX: WARNING: FIX: TODO: use `trusted-public-keys` instead
+  nix.settings.trusted-users = [user];
+
+  # ensure deployment user has SSH permissions
+  services.openssh.settings.AllowUsers = [user];
+
+  users = lib.mkIf isStandardDeployUser {
+    groups.${user} = {};
+
+    users.${user} = {
+      enable = true;
+      description = "Cerulean's user for building and remote deployment.";
+
+      isSystemUser = true;
+      group = user;
+
+      createHome = true;
+      home = "/var/lib/cerulean/cerubld";
+
+      useDefaultShell = false;
+      shell = pkgs.bash;
+
+      openssh.authorizedKeys.keys = node.deploy.ssh.publicKeys;
+    };
+  };
+}

nix/snow/default.nix

@@ -0,0 +1,191 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  this,
+  self,
+  inputs,
+  systems,
+  nt,
+  mix,
+  ...
+} @ args: let
+  inherit
+    (builtins)
+    all
+    attrNames
+    elem
+    mapAttrs
+    warn
+    ;
+
+  inherit (inputs.nixpkgs) lib;
+
+  inherit (nt) findImport;
+in
+  mix.newMixture args (mixture: let
+    inherit (mixture) mapNodes;
+  in {
+    includes.private = [
+      ./lib/nodes.nix
+    ];
+
+    inherit findImport;
+
+    # snow.flake
+    flake = flakeInputs: root: let
+      module = lib.evalModules {
+        class = "snowflake";
+        # TODO: abort if inputs contains reserved names
+        specialArgs =
+          (flakeInputs
+            // {
+              inherit systems root;
+              inherit (this) snow;
+              inputs = flakeInputs;
+            })
+          |> (x: builtins.removeAttrs x ["self" "nodes"]);
+
+        modules = [
+          ./module.nix
+          ({config, ...}: {
+            _module.args = {
+              self = config;
+              nodes = config.nodes.nodes;
+            };
+          })
+        ];
+      };
+
+      nodes = module.config.nodes;
+    in rec {
+      nixosConfigurations = mapNodes nodes (
+        {
+          base,
+          lib,
+          name,
+          node,
+          groupModules,
+          ...
+        }: let
+          homeManager =
+            if node.homeManager != null
+            then node.homeManager
+            else if nodes.homeManager != null
+            then nodes.homeManager
+            else
+              warn ''
+                [snowflake] Neither `nodes.homeManager` nor `nodes.nodes.${name}.homeManager` were specified!
+                [snowflake] home-manager will NOT be used! User configuration will be ignored!
+              ''
+              null;
+
+          userArgs = nodes.args // node.args;
+          ceruleanArgs = {
+            inherit systems root base nodes node;
+            inherit (node) system;
+            inherit (this) snow;
+            hostname = name;
+
+            _cerulean = {
+              inherit inputs userArgs ceruleanArgs homeManager;
+              specialArgs = userArgs // ceruleanArgs;
+            };
+          };
+          specialArgs = assert (userArgs
+            |> attrNames
+            |> all (argName:
+              ! ceruleanArgs ? argName
+              || abort ''
+                `specialArgs` are like super important to Cerulean my love... </3
+                But `args.${argName}` is a reserved argument name :(
+              ''));
+            ceruleanArgs._cerulean.specialArgs;
+        in
+          lib.nixosSystem {
+            inherit (node) system;
+            inherit specialArgs;
+            modules =
+              [
+                self.nixosModules.default
+                (findImport /${root}/hosts/${name})
+              ]
+              ++ (groupModules root)
+              ++ node.modules
+              ++ nodes.modules;
+          }
+      );
+
+      deploy.nodes = mapNodes nodes ({
+        name,
+        node,
+        ...
+      }: let
+        inherit
+          (node.deploy)
+          ssh
+          user
+          interactiveSudo
+          remoteBuild
+          rollback
+          autoRollback
+          magicRollback
+          activationTimeout
+          confirmTimeout
+          ;
+
+        nixosFor = system: inputs.deploy-rs.lib.${system}.activate.nixos;
+      in {
+        hostname =
+          if ssh.host != null
+          then ssh.host
+          else "";
+
+        profilesOrder = ["default"]; # profiles priority
+        profiles.default = {
+          path = nixosFor node.system nixosConfigurations.${name};
+
+          user = user;
+          sudo = "sudo -u";
+          interactiveSudo = interactiveSudo;
+
+          fastConnection = false;
+
+          autoRollback = autoRollback -> rollback;
+          magicRollback = magicRollback -> rollback;
+          activationTimeout = activationTimeout;
+          confirmTimeout = confirmTimeout;
+
+          remoteBuild = remoteBuild;
+          sshUser = ssh.user;
+          sshOpts =
+            ssh.opts
+            ++ (
+              if elem "-p" ssh.opts
+              then []
+              else ["-p" (toString ssh.port)]
+            )
+            ++ (
+              if elem "-A" ssh.opts
+              then []
+              else ["-A"]
+            );
+        };
+      });
+
+      checks =
+        inputs.deploy-rs.lib
+        |> mapAttrs (system: deployLib:
+          deployLib.deployChecks deploy);
+    };
+  })

nix/snow/lib/nodes.nix

@@ -0,0 +1,96 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{nt, ...}: let
+  inherit
+    (builtins)
+    concatLists
+    elem
+    filter
+    isAttrs
+    mapAttrs
+    pathExists
+    typeOf
+    ;
+
+  rootGroupName = "all";
+
+  parseGroupsDecl = groups: let
+    validGroup = g:
+      isAttrs g
+      || throw ''
+        Cerulean Nexus groups must be provided as attribute sets, got "${typeOf g}" instead!
+        Ensure all the group definitions are attribute sets under your call to `cerulean.mkNexus`.
+        NOTE: Groups can be accessed via `self.groups.PATH.TO.YOUR.GROUP`
+      '';
+    delegate = parent: gName: g: let
+      result =
+        (g
+          // {
+            _name = gName;
+            _parent = parent;
+          })
+        |> mapAttrs (name: value:
+          if elem name ["_name" "_parent"]
+          # ignore metadata fields
+          then value
+          else assert validGroup value; (delegate result name value));
+    in
+      result;
+  in
+    assert validGroup groups;
+      delegate null rootGroupName groups;
+
+  getGroupModules = root: groups:
+  # ensure root group is always added
+    groups
+    # add all inherited groups via _parent
+    |> map (let
+      delegate = g:
+        if g._parent == null
+        then [g]
+        else [g] ++ delegate (g._parent);
+    in
+      delegate)
+    # flatten recursion result
+    |> concatLists
+    # find import location
+    |> map (group: nt.findImport /${root}/groups/${group._name})
+    # filter by uniqueness
+    |> nt.prim.unique
+    # ignore missing groups
+    |> filter pathExists;
+in {
+  mapNodes = nodes: f:
+    nodes.nodes
+    |> mapAttrs (name: node: let
+      # use per-node base or default to nodes' base
+      base =
+        if node.base != null
+        then node.base
+        else if nodes.base != null
+        then nodes.base
+        else
+          abort ''
+            Cerulean cannot construct nodes node "${name}" without a base package source.
+            Ensure `nodes.nodes.*.base` or `nodes.base` is a flake reference to the github:NixOS/nixpkgs repository.
+          '';
+    in
+      f rec {
+        inherit name node base;
+        inherit (base) lib;
+
+        groups = node.groups (parseGroupsDecl nodes.groups);
+        groupModules = root: getGroupModules root groups;
+      });
+}

nix/snow/module.nix

@@ -0,0 +1,23 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  root,
+  snow,
+  ...
+}: {
+  imports = [
+    ./nodes
+    (snow.findImport /${root}/snow)
+  ];
+}

nix/snow/nodes/default.nix

@@ -0,0 +1,62 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  lib,
+  specialArgs,
+  ...
+}: {
+  options.nodes = let
+    inherit
+      (lib)
+      mkOption
+      types
+      ;
+  in
+    mkOption {
+      description = ''
+        Cerulean node declarations.
+      '';
+      type = types.submoduleWith {
+        inherit specialArgs;
+
+        modules = [
+          {
+            imports = [./shared.nix];
+
+            options = {
+              groups = mkOption {
+                type = types.attrs;
+                default = {};
+                example = lib.literalExpression "{ servers = { staging = {}; production = {}; }; }";
+                description = ''
+                  Hierarchical groups that nodes can be a member of.
+                '';
+              };
+
+              nodes = mkOption {
+                type = types.attrsOf (types.submoduleWith {
+                  inherit specialArgs;
+                  modules = [(import ./submodule.nix)];
+                });
+                # example = { ... }; # TODO
+                description = ''
+                  Node (host systems) declarations.
+                '';
+              };
+            };
+          }
+        ];
+      };
+    };
+}

nix/snow/nodes/shared.nix

@@ -0,0 +1,82 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{lib, ...}: let
+  inherit
+    (lib)
+    mkOption
+    types
+    ;
+
+  flakeRef = types.either types.str types.path;
+in {
+  options = {
+    base = lib.mkOption {
+      # In newer Nix versions, particularly with lazy trees, outPath of
+      # flakes becomes a Nix-language path object. We deliberately allow this
+      # to gracefully come through the interface in discussion with @roberth.
+      #
+      # See: https://github.com/NixOS/nixpkgs/pull/278522#discussion_r1460292639
+      type = types.nullOr flakeRef;
+
+      default = null;
+      defaultText = "if (using nixpkgsFlake.lib.nixosSystem) then self.outPath else null";
+
+      example = lib.literalExpression "inputs.nixpkgs";
+
+      description = ''
+        The path to the nixpkgs source used to build a system. A `base` package set
+        is required to be set, and can be specified via either:
+        1. `options.nodes.base` (default `base` used for all systems)
+        2. `options.nodes.nodes.<name>.base` (takes prescedence over `options.nodes.base`)
+
+        This can also be optionally set if the NixOS system is not built with a flake but still uses
+        pinned sources: set this to the store path for the nixpkgs sources used to build the system,
+        as may be obtained by `fetchTarball`, for example.
+
+        Note: the name of the store path must be "source" due to
+        <https://github.com/NixOS/nix/issues/7075>.
+      '';
+    };
+
+    modules = mkOption {
+      type = types.listOf types.raw;
+      default = [];
+      example = lib.literalExpression "[ { environment.systemPackages = [ pkgs.git ]; } ]";
+      description = ''
+        Shared modules to import; equivalent to the NixOS module system's `extraModules`.
+      '';
+    };
+
+    args = mkOption {
+      type = types.attrs;
+      default = {};
+      example = lib.literalExpression "{ inherit inputs; }";
+      description = ''
+        Shared args to provided for each node; equivalent to the NixOS module system's `specialArgs`.
+      '';
+    };
+
+    homeManager = mkOption {
+      type = types.nullOr flakeRef;
+      default = null;
+      example = lib.literalExpression "inputs.home-manager";
+      description = ''
+        The path to the home-manager source. A `homeManager` flake reference
+        is required to be set for `homes/` to be evaluated, and can be specified via either:
+        1. `options.nodes.homeManager` (default `homManager` used for all systems)
+        2. `options.nodes.nodes.<name>.homeManager` (takes prescedence over `options.nodes.homeManager`)
+      '';
+    };
+  };
+}

nix/snow/nodes/submodule.nix

@@ -0,0 +1,204 @@
+# Copyright 2025-2026 _cry64 (Emile Clark-Boman)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+{
+  lib,
+  systems,
+  ...
+}: {
+  imports = [./shared.nix];
+
+  options = let
+    inherit
+      (lib)
+      mkOption
+      types
+      ;
+  in {
+    enabled = lib.mkOption {
+      type = types.bool;
+      default = true;
+      example = true;
+      description = ''
+        Whether to enable this node. Nodes are enabled by default.
+      '';
+    };
+
+    system = mkOption {
+      type = types.nullOr (types.enum systems);
+      default = null;
+      example = "x86_64-linux";
+      description = ''
+        The target system architecture to compile for.
+      '';
+    };
+
+    groups = mkOption {
+      # TODO: write a custom group type that validates better than types.attrs lol
+      type = types.functionTo (types.listOf types.attrs);
+      default = groups: [];
+      example = lib.literalExpression "( groups: [ groups.servers groups.secure-boot ] )";
+      description = ''
+        A function from the `groups` hierarchy to a list of groups this node inherits from.
+      '';
+    };
+
+    deploy = {
+      user = mkOption {
+        type = types.str;
+        default = "root";
+        example = "admin";
+        description = ''
+          The user that the system derivation will be built with. The command specified in
+          `<node>.deploy.sudoCmd` will be used if `<node>.deploy.user` is not the
+          same as `<node>.deploy.ssh.user` the same as above).
+        '';
+      };
+
+      warnNonstandardDeployUser = mkOption {
+        type = types.bool;
+        default = true;
+        example = false;
+        description = ''
+          Disables the warning that shows when `deploy.ssh.user` is set to a non-standard value.
+        '';
+      };
+
+      # sudoCmd = mkOption {
+      #   type = types.str;
+      #   default = "sudo -u";
+      #   example = "doas -u";
+      #   description = ''
+      #     Which sudo command to use. Must accept at least two arguments:
+      #     1. the user name to execute commands as
+      #     2. the rest is the command to execute
+      #   '';
+      # };
+
+      interactiveSudo = mkOption {
+        type = types.bool;
+        default = false;
+        example = false;
+        description = ''
+          Whether to enable interactive sudo (password based sudo).
+          NOT RECOMMENDED. Use one of Cerulean's recommended auth methods instead.
+        '';
+      };
+
+      remoteBuild = mkOption {
+        type = types.bool;
+        default = false;
+        example = false;
+        description = ''
+          Whether to build the system derivation on the target system.
+          Will also fetch all external dependencies from the target system's substituters.
+        '';
+      };
+
+      rollback = mkOption {
+        type = types.bool;
+        default = true;
+        example = true;
+        description = ''
+          Enables both `autoRollback` and `magicRollback`.
+        '';
+      };
+
+      autoRollback = mkOption {
+        type = types.bool;
+        default = true;
+        example = true;
+        description = ''
+          If the previous system derivation should be re-activated if activation fails.
+        '';
+      };
+
+      magicRollback = mkOption {
+        type = types.bool;
+        default = true;
+        example = true;
+        description = ''
+          TODO: im fucking lazy
+        '';
+      };
+
+      activationTimeout = mkOption {
+        type = types.int;
+        default = 500;
+        example = 30;
+        description = ''
+          Time window in seconds allowed for system derivation activation.
+          If timeout occurs, remote deployment is considered to have failed.
+        '';
+      };
+
+      confirmTimeout = mkOption {
+        type = types.int;
+        default = 30;
+        example = 15;
+        description = ''
+          Time window in seconds allowed for activation confirmation.
+          If timeout occurs, remote deployment is considered to have failed.
+        '';
+      };
+
+      ssh = {
+        host = mkOption {
+          type = types.nullOr types.str;
+          default = null;
+          example = "dobutterfliescry.net";
+          description = ''
+            The host to connect to over ssh during deployment
+          '';
+        };
+
+        user = mkOption {
+          type = types.str;
+          default = "cerubld";
+          example = "custom-user";
+          description = ''
+            The user to connect to over ssh during deployment.
+          '';
+        };
+
+        port = mkOption {
+          type = types.int;
+          default = 22;
+          example = 2222;
+          description = ''
+            The port to connect to over ssh during deployment.
+          '';
+        };
+
+        publicKeys = mkOption {
+          type = types.listOf types.str;
+          default = [];
+          example = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIeyZuUUmyUYrYaEJwEMvcXqZFYm1NaZab8klOyK6Imr me@puter"];
+          description = ''
+            SSH public keys that will be authorized to the deployment user.
+            This key is intended solely for deployment, allowing for fine-grained permission control.
+          '';
+        };
+
+        opts = mkOption {
+          type = types.listOf types.str;
+          default = [];
+          example = ["-i" "~/.ssh/id_rsa"];
+          description = ''
+            Extra ssh arguments to use during deployment.
+          '';
+        };
+      };
+    };
+  };
+}