Creating your first clan

Ready to manage your fleet of machines?

We will create a declarative infrastructure using clan, git, and nix flakes.

You'll finish with a centrally managed fleet, ready to import your existing NixOS configuration.

Prerequisites

Make sure you have the following:

• 💻 Administration Machine: Run the setup commands from this machine.

• 🛠️ Nix: The Nix package manager, installed on your administration machine.

  How to install Nix (Linux / MacOS / NixOS)

  On Linux or macOS:

  1. Run the recommended installer:

     curl --proto '=https' --tlsv1.2 -sSf -L [https://install.determinate.systems/nix](https://install.determinate.systems/nix) | 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 in your configuration.nix:

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

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

• 🎯 Target Machine(s): A remote machine with SSH, or your local machine (if NixOS).

Create a New Clan

1. Navigate to your desired directory:

   cd <your-directory>
   

2. Create a new clan flake:

   Note: This creates a new directory in your current location

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

3. Enter a name in the prompt:

   Enter a name for the new clan: my-clan
   

Project Structure

Your new directory, my-clan, should contain the following structure:

my-clan/
├── clan.nix
├── flake.lock
├── flake.nix
├── modules/
└── sops/

Activate the Environment

To get started, cd into your new project directory.

cd my-clan

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

nix profile install nixpkgs#direnv

nix profile install nixpkgs#nix-direnv

• Direnv needs to hook into your shell to work. You can do this by executing following command. The example below will setup direnv for zsh and bash

  echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && eval "$SHELL"
  

  Run direnv allow to automatically load the environment whenever you enter this directory.

  direnv allow
  

nix develop

Verify the Setup

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 tld by editing the meta.name and meta.tld fields in your clan.nix file.

{
  # Ensure this is unique among all clans you want to use.
  meta.name = "__CHANGE_ME__";
  meta.tld = "changeme";

  # ...
  # elided
}