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
}
-
See reference/clanServices for all available services and how to configure them. Or read authoring/clanServices if you want to bring your own
-
Replace
__YOUR_CONTROLLER_
with the name of your machine. -
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
};
}
- The
admin
service will generate a root-password and add your ssh-key that allows for convienient administration. - Equivalent to directly setting
authorizedKeys
like in configuring a machine - Adds
user = jon
as a user on all machines. Will create ahome
directory, and prompt for a password before deployment.