Skip to content

Getting Started

Ready to create your own Clan and manage a fleet of machines? Follow these simple steps to get started.

By the end of this guide, you'll have a fresh NixOS configuration ready to push to one or more machines. You'll create a new Git repository and a flake, and all you need is at least one machine to push to. This is the easiest way to begin, and we recommend you to copy your existing configuration into this new setup!

Prerequisites

Clan requires Nix to be installed on your system. Run the following command to install Nix:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

If you have previously installed Nix, make sure experimental-features = nix-command flakes is present in ~/.config/nix/nix.conf or /etc/nix/nix.conf. If this is not the case, please add it to ~/.config/nix/nix.conf.

If you run NixOS the nix binary is already installed.

You will also need to enable the nix-command and flakes experimental features in your configuration.nix:

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

Clan requires Nix to be installed on your system. Run the following command to install Nix:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

If you have previously installed Nix, make sure experimental-features = nix-command flakes is present in ~/.config/nix/nix.conf or /etc/nix/nix.conf. If this is not the case, please add it to ~/.config/nix/nix.conf.

Add Clan CLI to Your Shell

Add the Clan CLI into your environment:

nix shell git+https://git.clan.lol/clan/clan-core#clan-cli --refresh

clan --help

Should print the avilable commands.

Also checkout the cli-reference documentation.

Initialize Your Project

If you want to migrate an existing project, follow this guide.

Set the foundation of your Clan project by initializing it by running:

clan flakes create my-clan

This command creates a flake.nix and some other files for your project.

Explore the Project Structure

Take a lookg at all project files:

cd my-clan
tree

For example, you might see something like:

.
├── flake.nix
├── machines/
├── modules/
└── README.md

Don’t worry if your output looks different—the template evolves over time.

Recommended way of sourcing the clan CLI tool

The default template adds the clan CLI tool to the development shell. This means that you can access the clan CLI tool directly from the folder you are in right now.

In the my-clan directory, run the following command:

nix develop

This will ensure the clan CLI tool is available in your shell environment.

To automatically add the clan CLI tool to your environment without having to run nix develop every time, we recommend setting up direnv.

clan show

You should see something like this:

Name: my-clan
Description: None

Next Steps

You can continue with any of the following steps at your own pace: