Deployment Options

You are currently reading the unstable version of the Colmena Manual, built against the tip of the development branch.

Colmena adds a set of extra options that can be used in your NixOS configurations under the deployment prefix.


Allow the configuration to be applied locally on the host running Colmena.

For local deployment to work, all of the following must be true:

  • The node must be running NixOS.
  • The node must have deployment.allowLocalDeployment set to true.
  • The node’s networking.hostName must match the hostname.

To apply the configurations locally, run colmena apply-local. You can also set deployment.targetHost to null if the nost is not accessible over SSH (only local deployment will be possible).

Type: boolean

Default: false


Whether to build the system profiles on the target node itself.

When enabled, Colmena will copy the derivation to the target node and initiate the build there. This avoids copying back the build results involved with the native distributed build feature. Furthermore, the build goal will be equivalent to the push goal. Since builds happen on the target node, the results are automatically “pushed” and won’t exist in the local Nix store.

You can temporarily override per-node settings by passing --build-on-target (enable for all nodes) or --no-build-on-target (disable for all nodes) on the command line.

Type: boolean

Default: false


A set of secrets to be deployed to the node.

Secrets are transferred to the node out-of-band and never ends up in the Nix store.

Type: attribute set of (submodule)

Default: { }


Destination directory on the host.

Type: path

Default: "/run/keys"


The group that will own the file.

Type: string

Default: "root"


Command to run to generate the key. One of text, keyCommand and keyFile must be set.

Type: null or (list of string)

Default: null


Path of the local file to read the key from. One of text, keyCommand and keyFile must be set.

Type: null or path

Default: null


File name of the key.

Type: string

Default: "‹name›"


Permissions to set for the file.

Type: string

Default: "0600"


Content of the key. One of text, keyCommand and keyFile must be set.

Type: null or string

Default: null


When to upload the keys.

  • pre-activation (default): Upload the keys before activating the new system profile.
  • post-activation: Upload the keys after successfully activating the new system profile.

For colmena upload-keys, all keys are uploaded at the same time regardless of the configuration here.

Type: one of “pre-activation”, “post-activation”

Default: "pre-activation"


The group that will own the file.

Type: string

Default: "root"


Command to use to elevate privileges when activating the new profiles on SSH hosts.

This is used on SSH hosts when deployment.targetUser is not root. The user must be allowed to use the command non-interactively.

Type: list of string




Allow a configuration to be applied to a host running a profile we have no knowledge of. By setting this option to false, you reduce the likelyhood of rolling back changes made via another Colmena user.

Unknown profiles are usually the result of either:

  • The node had a profile applied, locally or by another Colmena.
  • The host running Colmena garbage-collecting the profile.

To force profile replacement on all targeted nodes during apply, use the flag --force-replace-unknown-profiles.

Type: boolean

Default: true


Extra SSH options to pass to the SSH command.

Type: list of string

Default: [ ]


A list of tags for the node.

Can be used to select a group of nodes for deployment.

Type: list of string

Default: [ ]


The target SSH node for deployment.

By default, the node’s attribute name will be used. If set to null, only local deployment will be supported.

Type: null or string

Default: "nixos"


The target SSH port for deployment.

By default, the port is the standard port (22) or taken from your ssh_config.

Type: null or unsigned integer, meaning >=0

Default: null


The user to use to log into the remote node. If set to null, the target user will not be specified in SSH invocations.

Type: null or string

Default: "root"