runNixOps :: AttrSet → Effect

Provision interrelated machine configurations and other cloud resources.

For a practical introduction, check out the guide Deploy a NixOps 1.x Network.



The NixOps deployment name.


NixOps network expressions and other files required for the deployment. Unlike some other deployment methods, NixOps needs access to the actual expression files.

Confidential information should not be committed and included here, but inserted via secrets.json and userSetupScript.


Default: ["network.nix"]

Files in src that are always used as network expressions.


Default: true

Whether to build the network during the Hercules CI build phase. This ensures that all packages are in the cache and avoids attempting a deployment when some packages can’t be built.


Default: []

Prebuild runs outside of NixOps, which means that some info may be missing. Specify extra network expressions here to fill in or override the missing definitions.


Default: []

Network files that are only used when deploying; not when prebuilding.


Default: "nixops-${name}.json"

Override the Hercules CI state file name, in case it’s necessary.

The state file only contains a single deployment.


Default: "nixops-${name}.known_hosts"

Some NixOps backends do not update the ~/.ssh/known_hosts file. runNixOps will persist this file as a state file with the name set here.


Default: "nixpkgs=${pkgs.path}", where pkgs is the Nixpkgs invocation that included the effects overlay.

Necessary for looking up <nixpkgs> or potentially other locations using angle bracket syntax.


Default: "switch"; performing a full deployment, analogous to nixos-rebuild switch but on all nodes and including resources.

Other valid values besides "switch" are "dry-run", "plan", "build"*, "create", "copy", "dry-activate", "test", "boot".

Note that your agent will not automatically push to the cache for build. prebuild (enabled by default) does take care of this. See also the NixOps deployment guide on prebuilding.

…​ — remaining arguments

Other attributes are passed to mkEffect, which passes its remaining arguments to mkDerivation.

Return value

An effect that performs the specified action on the NixOps deployment.

The effect has the following attributes in addition to the attributes returned by mkEffect.


A derivation representing the built system configuration.


An attribute set containing the NixOS configurations of the prebuilt nodes.

This is primarily useful for inspection with nix repl.


An attribute set with various attributes, including resources.

This is primarily useful for inspection with nix repl.

See also

  • runNixOps2 — similar function for NixOps 2

  • runNixOS — a simpler solution for single pre-existing machines

  • runArion — deploy services to Docker using NixOS, Nix or Docker-based images