Creating Your First Clan

Summary

Ready to manage your fleet of machines?

In this guide, we will create a declarative infrastructure using clan, git, and nix flakes.

At the end of this getting started guide, you will have a centrally managed fleet of Clan devices at your disposal.

If you want to migrate your existing systems instead of following this guide for a completely fresh setup, please find the corresponding links in our Guides database instead. Note that you can also always migrate your existing systems into the new Clan after following this getting started guide, too.

Requirements

  • Expected knowledge levels for this guide: Linux 2/5 - NixOS 0/5 - Computer Networks 1/5

  • Estimated time for this step: 20 minutes

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

    Operating System Recommendations

    We are currently working on more refined operating system recommendations.

    • Minimum system requirements: 2 CPUs, 4GB RAM, 30gb HDD space, network interface

    • We currently recommend NixOS 25.11 for this guide, but other Linux systems are supported, too.

    • Root user access will be required throughout the whole setup.

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

    How to install Nix

    On Linux (or macOS):

    1. Run the recommended installer:

      curl -sSfL 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)

    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. Verify installation:

      direnv --version
    Other Linux

    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 machine 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.

  • 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/25.11.tar.gz#clan-cli" --refresh -- flakes create

  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/
Templates

This is the structure for the default template.

Use clan templates list and clan templates --help for available templates & more. Keep in mind that the exact files may change as templates evolve.

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.

Automatic (direnv, recommended)

If you installed direnv correctly following the required steps before, you should be presented with an error message now:

direnv: error /MY-DIRECTORY/MY-NEW-CLAN/.envrc is blocked. Run direnv allow to approve its content

To continue, simply allow direnv in your Clan directory:

direnv allow
Manual (nix develop)

Run nix develop to load the environment manually:

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. It is recommended to use the same name you entered during the creation process.
  • meta.domain will function as your internal top level domain. Select something catchy, like clan.lol

Feel obliged to change the following lines

clan.nix{
  # Ensure this is unique among all clans you want to use.
  meta.name = "fancyclan";
  meta.domain = "fancydomain";
  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: __CHANGE_ME__
Description: None

This confirms your setup is working correctly.

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

The meta.name will reflect the name of your clan. It is recommended to use the same name you entered during the creation process.

The meta.domain will function as your internal top level domain. Select something catchy, like clan.lol

Feel free to add meta.description = "something smart" beneath meta.domain if you would like to update the description for clan show.

clan.nix{
  # Ensure this is unique among all clans you want to use.
  meta.name = "__CHANGE_ME__";
  meta.domain = "changeme";
  meta.description = "optional";
}

Up Next

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