clan-core/docs/site/guides/macos.md

Managing macOS Machines with Clan

This guide explains how to manage macOS machines using Clan.

Supported Features

Currently, Clan supports the following features for macOS:

• clan machines update for existing nix-darwin installations
• Support for vars

Step 1: Add Your Machine to Your Clan Flake

In this example, we'll name the machine yourmachine. Replace this with your preferred machine name.

=== "If using core.lib.buildClan"

buildClan {
    inventory = {
        machines.yourmachine.machineClass = "darwin";
    };
}

=== "If using flake-parts"

{
  clan = {
    inventory = {
        machines.yourmachine.machineClass = "darwin";
    };
  };
}

Step 2: Add a configuration.nix for Your Machine

Create the file ./machines/yourmachine/configuration.nix with the following content (replace yourmachine with your chosen machine name):

{
  clan.core.networking.targetHost = "root@ip_or_hostname";
  nixpkgs.hostPlatform = "aarch64-darwin"; # Use "x86_64-darwin" for Intel-based Macs
}

After creating the file, run git add to ensure Nix recognizes it.

Step 3: Generate Vars (If Needed)

If your machine uses vars, generate them with:

clan vars generate yourmachine

Replace yourmachine with your chosen machine name.

Step 4: Install Nix

Install Nix on your macOS machine using one of the methods described in the nix-darwin prerequisites.

Step 5: Install nix-darwin

Upload your Clan flake to the macOS machine. Then, from within your flake directory, run:

sudo nix run nix-darwin/master#darwin-rebuild -- switch --flake .#yourmachine

Replace yourmachine with your chosen machine name.

Step 6: Manage Your Machine with Clan

Once all the steps above are complete, you can start managing your machine with:

clan machines update yourmachine

This command can be run from any computer that can reach this machine via SSH.