clan-core/docs/site/guides/getting-started/add-services.md

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.

Configure a Zerotier Network (recommended)

{
    inventory.machines = {
        jon = { };
        sara = { };
    };

    inventory.instances = {
        zerotier = { # (1)
            # Replace with the name (string) of your machine that you will use as zerotier-controller
            # See: https://docs.zerotier.com/controller/
            # Deploy this machine first to create the network secrets
            roles.controller.machines."jon" = { }; # (2)
            # Peers of the network
            # this line means 'all' clan machines will be 'peers'
            roles.peer.tags.all = { }; # (3)
        };
    };
    # ...
    # elided
}

1. See reference/clanServices for all available services and how to configure them. Or read authoring/clanServices if you want to bring your own

2. Replace __YOUR_CONTROLLER_ with the name of your machine.

3. This line will add all machines of your clan as peer to zerotier

Adding more recommended defaults

Adding the following services is recommended for most users:

{
    inventory.machines = {
        jon = { };
        sara = { };
    };
    inventory.instances = {
        admin = { # (1)
            roles.default.tags.all = { };
            roles.default.settings = {
                allowedKeys = {
                    "my-user" = "ssh-ed25519 AAAAC3N..."; # (2)
                };
            };
        };
        # ...
        # elided
    };
}

1. The admin service will generate a root-password and add your ssh-key that allows for convienient administration.
2. Equivalent to directly setting authorizedKeys like in configuring a machine
3. Adds user = jon as a user on all machines. Will create a home directory, and prompt for a password before deployment.