Skip to content

How to add services

A service in clan is a self-contained, reusable unit of system configuration that provides a specific piece of functionality across one or more machines.

Think of it as a recipe for running a tool — like automatic backups, VPN networking, monitoring, etc.

In Clan Services are multi-Host & role-based:

  • Roles map machines to logical service responsibilities, enabling structured, clean deployments.

  • You can use tags instead of explicit machine names.

To learn more: Guide about clanService

Important

It is recommended to add at least one networking service such as zerotier that allows to reach all your clan machines from your setup computer across the globe.

flake.nix
{
    inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
    inputs.nixpkgs.follows = "clan-core/nixpkgs";
    inputs.flake-parts.follows = "clan-core/flake-parts";
    inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs";

    outputs =
        inputs@{ flake-parts, ... }:
        flake-parts.lib.mkFlake { inherit inputs; } {
            imports = [ inputs.clan-core.flakeModules.default ];
            clan = {
                inventory.machines = {
                    jon = {
                        targetHost = "root@jon";
                    };
                    sara = {
                        targetHost = "root@jon";
                    };
                };
                inventory.instances = {
                    zerotier = { # (1)
                        # Defines 'jon' as the controller
                        roles.controller.machines.jon = {};
                        # Defines all machines as networking peer.
                        # The 'all' tag is a clan builtin.
                        roles.peer.tags.all = {};
                    };
                }
            };

            systems = [
                "x86_64-linux"
                "aarch64-linux"
                "x86_64-darwin"
                "aarch64-darwin"
            ];
    };
}
  1. See reference/clanServices for all available services and how to configure them. Or read authoring/clanServices if you want to bring your own

Adding the following services is recommended for most users:

flake.nix
{
    inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
    inputs.nixpkgs.follows = "clan-core/nixpkgs";
    inputs.flake-parts.follows = "clan-core/flake-parts";
    inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs";

    outputs =
        inputs@{ flake-parts, ... }:
        flake-parts.lib.mkFlake { inherit inputs; } {
            imports = [ inputs.clan-core.flakeModules.default ];
            clan = {
                inventory.machines = {
                    jon = {
                        targetHost = "root@jon";
                    };
                    sara = {
                        targetHost = "root@jon";
                    };
                };
                inventory.instances = {
                    zerotier = {
                        roles.controller.machines.jon = {};
                        roles.peer.tags.all = {};
                    };
                    admin = { # (1)
                        roles.default.tags.all = { };
                        roles.default.settings = {
                            allowedKeys = {
                                "my-user" = "ssh-ed25519 AAAAC3N..."; # elided
                            };
                        };
                    };
                    state-version = { # (2)
                        roles.default.tags.all = { };
                    };
                };
            };
            systems = [
                "x86_64-linux"
                "aarch64-linux"
                "x86_64-darwin"
                "aarch64-darwin"
            ];
    };
}

  1. The admin service will generate a root-password and add your ssh-key that allows for convienient administration.

  2. The state-version service will generate a nixos state version for each system once it is deployed.