Update Machines

The Clan command line interface enables you to update machines remotely over SSH. In this guide we will teach you how to set a targetHost in Nix, and how to define a remote builder for your machine closures.

Setting targetHost

Set the machine’s targetHost to the reachable IP address of the new machine. This eliminates the need to specify --target-host in CLI commands.

{
# Ensure this is unique among all clans you want to use.
meta.name = "my-clan";

inventory.machines = {
    # Define machines here.
    # The machine name will be used as the hostname.
    jon = {
        deploy.targetHost = "root@192.168.192.4"; # (1)
    };
};
# [...]
}

The use of root@ in the target address implies SSH access as the root user. Ensure that the root login is secured and only used when necessary.

Multiple Target Hosts

You can now experiment with a new interface that allows you to define multiple targetHost addresses for different VPNs. Learn more and try it out in our networking guide.

Updating Machine Configurations

Execute the following command to update the specified machine:

clan machines update jon

All machines can be updated simultaneously by omitting the machine name:

clan machines update

Advanced Usage

The following options are only needed for special cases, such as limited resources, mixed environments, or private flakes.

Setting buildHost

If the machine does not have enough resources to run the NixOS evaluation or build itself, it is also possible to specify a buildHost instead. During an update, clan will ssh into the buildHost and run nixos-rebuild from there.

buildClan {
    # ...
    machines = {
        "jon" = {
            clan.core.networking.buildHost = "root@<host_or_ip>";
        };
    };
};

Overriding configuration with CLI flags

buildHost / targetHost, and other network settings can be temporarily overridden for a single command:

For the full list of flags refer to the Clan CLI

# Build on a remote host
clan machines update jon --build-host root@192.168.1.10

# Build locally (useful for testing or when the target has limited resources)
clan machines update jon --build-host local

Excluding a machine from clan machine update

To exclude machines from being updated when running clan machines update without any machines specified, one can set the clan.deployment.requireExplicitUpdate option to true:

buildClan {
    # ...
    machines = {
        "jon" = {
            clan.deployment.requireExplicitUpdate = true;
        };
    };
};

This is useful for machines that are not always online or are not part of the regular update cycle.

Uploading Flake Inputs

When updating remote machines, flake inputs are usually fetched by the build host. However, if flake inputs require authentication (e.g., private repositories),

Use the --upload-inputs flag to upload all inputs from your local machine:

clan machines update jon --upload-inputs

This is particularly useful when: - The flake references private Git repositories - Authentication credentials are only available on local machine - The build host doesn't have access to certain network resources