Creating your first clan

Create a declarative infrastructure using Clan, git, and Nix.

To migrate existing systems instead, see the Guides.

Requirements

• One Setup Device: A Linux device from which the setup commands will be run.

  Minimum system requirements: 2 CPUs, 4GB RAM, 30GB HDD, network interface. We recommend NixOS 25.11, but other Linux systems work too. Root access required.

• Nix: The Nix package manager installed on your setup device.

  How to install Nix

  On Linux (or macOS):

  1. Run the recommended installer:

     curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/nix-installer | sh -s -- install
     

  2. After installation, ensure flakes are enabled by adding this line to ~/.config/nix/nix.conf:

     experimental-features = nix-command flakes
     

  On NixOS:

  Nix is already installed. You only need to enable flakes for your user via nano /etc/nixos/configuration.nix:

  {
    nix.settings.experimental-features = [ "nix-command" "flakes" ];
  }
  

  Then, run nixos-rebuild switch to apply the changes.

• direnv: Many commands in this guide will require direnv to be installed on your setup device.

  How to install direnv

  NixOS (recommended)Other Linux

  1. Add the required lines to your configuration.nix:

     {
       programs.direnv.enable = true;
       programs.direnv.nix-direnv.enable = true;
     }
     

  2. Run:

     sudo nixos-rebuild switch
     

  3. Reboot your system.

  4. Verify installation:

     direnv --version
     

  1. Install direnv:

     sudo apt install direnv
     

     or for Arch:

     sudo pacman -S direnv
     

  2. Add a hook to your shell:

     echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
     

     or for zsh:

     echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
     

  3. Restart your shell and then allow direnv for the current folder to test if it worked:

     direnv allow
     

• Target Device(s): Any number of physical and / or virtual Linux or macOS devices with SSH root access to. The minimum hardware requirements are equal to the setup device specs above.

  If your setup device is running on NixOS, it can also be included in the Clan we are going to build, but we will not address this option in this guide.

• SSH Keys On Setup Device: If not already done, generate a key pair for your root user on the setup device.

  Find or generate your keys

  1. As root, check if a key already exists:

     cat /root/.ssh/id_ed25519.pub
     

  2. If not, generate one:

     ssh-keygen -t ed25519
     

• In Case of Physical Target Device(s): A USB drive with at least 1.5GB total space (all data on it will be lost)

Create a New Clan

A "Clan" is the top level concept of the environment you are building.

In your Clan, you will create and manage your machines, users, and services. It can later also define the relation between services and machines via roles.

1. Navigate to your desired directory:

   cd <MY-DIRECTORY>
   

2. Create a new Clan flake:

   Note: This creates a new directory in your current location. Depending on your connection speed, this step may take a few minutes.

   nix run "https://git.clan.lol/clan/clan-core/archive/main.tar.gz#clan-cli" --refresh -- init
   

3. Enter a name in the prompt, for example MY-NEW-CLAN:

   Enter a name for the new clan: MY-NEW-CLAN
   

Project Structure

Your new directory, MY-NEW-CLAN, should contain the following structure:

MY-NEW-CLAN/
├── clan.nix
├── flake.lock
├── flake.nix
├── modules/
└── sops/

Activating the Environment

To get started, cd into your new project directory.

cd MY-NEW-CLAN

Now, activate the environment using one of the following methods.

direnv allow

nix develop

Renaming Your Clan

You can now change the default name and tld by editing the meta.name and meta.domain fields in your clan.nix file.

• meta.name will reflect the name of your clan.
• meta.domain will function as your internal top level domain. Select something catchy!
• meta.description is optional, we recommend using it for easy definitions.

Feel free to customize the highlighted values in the future:

{
  # Ensure this is unique among all clans you want to use.
  meta.name = "MY-NEW-CLAN";
  meta.domain = "mydomain";
  meta.description = "My selfhosted homelab";

}

See Clan options for all available options.

Checkpoint

Once your environment is active, verify that the Clan command is available by running:

clan show

You should see the default metadata for your new Clan:

Name: MY-NEW-CLAN
Description: My selfhosted homelab
Domain: mydomain

This confirms your setup is working correctly.

If you receive an error message for clan show, check for syntax errors in your clan.nix file first.

Up Next

We will add machines to your freshly created Clan during the next step.