Skip to content

Settings Reference

There are a number of settings available that can impact how nixbuild.net behaves when you use the service. The settings are represented as a flat list of key-value pairs. All settings have reasonable default values so you don't need to change anything, but it is recommended to read through this page to get a feeling for what is possible.

Some settings are named the same as standard Nix settings. These settings should have the same meaning in nixbuild.net as they have in Nix. Other settings are unique to nixbuild.net.

Settings can be configured on the following levels, in order of significance (settings defined later in this list overrides earlier settings):

  1. System configuration (default settings) — Not configurable by the end user.

  2. Account configuration — Settings that are used for all users of the same account. Configurable by end users through the nixbuild.net shell.

  3. SSH key configuration — Settings that are used for a specific SSH key. Configurable by end users through the nixbuild.net shell.

  4. SSH environment configuration — Settings used for a specific SSH session. Configurable by end users through their SSH client configuration. You must have set settings-from-ssh-env to true, otherwise the SSH environment settings are ignored. By default, settings-from-ssh-env is true.

  5. Nix derivation configuration — Settings used for a specific build. Configurable by end users by setting special attributes in their Nix derivations. You must have set settings-from-drv-env to true, otherwise the derivation settings are ignored. By default, settings-from-drv-env is false.

  6. Nix client settings — Nix allows some settings to be specified directly on the command line when running a build. Some of these settings will be passed on to remote builders. Unfortunately, very few of the available Nix settings are passed on, and it also varies depending how you run your build (if you use ssh:// or ssh-ng://, remote builds or remote stores). nixbuild.net tries to make the best of the situation and picks up any settings passed on to it. There are improvements needed in this area, both in Nix and nixbuild.net.

Configuration

Account

See the nixbuild.net shell documentation for instructions on how to configure account-wide settings.

SSH Key

You can override account settings for specific SSH keys. See the nixbuild.net shell documentation for instructions on how to configure key-specific overrides.

SSH Environment

Only used if settings-from-ssh-env is true (which is the default).

You can use the SetEnv option of OpenSSH to configure nixbuild.net via your SSH session. Each setting needs to capitalized, prepended with NIXBUILDNET_ and hyphens should be replace with underscores. This is an example of how your SSH client config could look like:

Host eu.nixbuild.net
  SetEnv NIXBUILDNET_KEEP_BUILDS_RUNNING=true NIXBUILDNET_REUSE_BUILD_FAILURES=false

Boolean true values are encoded with true or 1. False values are encoded with false, 0 or an empty string. For list settings (like substituters, caches etc) entries should be separated by a space or a comma.

You can make use of host aliases in you ssh configuration to create "virtual" builders that configure nixbuild.net in different ways.

There is also an option named SendEnv in OpenSSH, which works similarly to SetEnv, but picks the variable values from the current environment. Conveniently, SendEnv also supports wildcard matching. This means you can have the following SSH configuration:

Host eu.nixbuild.net
  SendEnv NIXBUILDNET_*

Then, any time you initiate a connection to eu.nixbuild.net, OpenSSH will look in the current environment and send any variables starting with NIXBUILDNET_. Note, however, if you are using nix-daemon to run builds, the environment that OpenSSH will search is the environment of the nix-daemon service, not your user environment.

Nix Derivation

Only used if settings-from-drv-env is true (which is not the default).

Use derivation attributes to use specific settings for individual builds:

mkDerivation {
  name = "...";
  src = ...;

  NIXBUILDNET_KEEP_BUILDS_RUNNING = true;
}

The variable names use the same format as the ssh environment does.

Available Settings

access-tokens

List of access tokens, default empty.

Defines tokens that are used to access private resources. This works much in the same way as the identically named Nix setting.

Currently, the only kind of token supported is Cachix per-cache auth tokens. These are used when uploading store paths directly from nixbuild.net to Cachix (see the caches setting), or when using private Cachix caches as substituters.

The format used for storing Cachix auth tokens in the access-tokens setting is cachix://<CACHE>=<ACCESS>:<TOKEN>. ACCESS is either READ (for read-only tokens) or WRITE (for tokens with write permissions). For uploading (caches), a token with write access must be added. For substitution (substituters), read or write tokens can be used. You can add different write and read tokens for the same Cachix cache if you like.

To add a write auth token for the Cachix cache mycache you would run:

nixbuild.net> settings access-tokens --add cachix://mycache=WRITE:<TOKEN>

If you leave out the READ: or WRITE: part, the token will be assumed to have write permissions.

To remove an access token, use --remove and leave out the actual token, like this:

nixbuild.net> settings access-tokens --remove cachix://mycache=WRITE:

The tokens you add are stored for your account in nixbuild.net. You should take care and try to use tokens with limited capabilities and short expiration times. An even better approach is to not store the tokens in the account settings or SSH key setting at all, but instead use the SSH environment. That way, the tokens will disappear from nixbuild.net when your SSH session ends. To pass access tokens in the SSH environment configure SSH like this:

SetEnv NIXBUILDNET_ACCESS_TOKENS=cachix://mycache=WRITE:<TOKEN>

Multiple tokens can be separated by spaces or commas.

always-substitute

Boolean, default true

If enabled, nixbuild.net will ignore the builders-use-substitutes setting reported by your Nix client, and always try to perform substitution from the substituters configured for your account.

caches

List of URLs, default empty.

The caches setting defines external caches that should be populated automatically by nixbuild.net during builds.

If assigned, nixbuild.net will upload the transitive closures of all inputs and outputs for every build that is executed, to all caches listed. nixbuild.net will perform upload of build inputs in parallel with running the build, to save time.

Currently, only Cachix caches are supported. You need to use a cache where the signing key is managed by Cachix, and have a write per-cache token for your cache. The token must be added to the access-tokens setting.

The format used for storing Cachix caches in the caches settings is cachix://<CACHE>. So, to add a Cachix cache named mycache, and its auth token you would run:

nixbuild.net> settings caches --add cachix://mycache
nixbuild.net> settings access-tokens --add cachix://mycache=WRITE:<TOKEN>

If you would like to see support for other types of caches in addition to Cachix, please contact [email protected].

See also ignore-cache-failures.

default-permissions

List of permissions, defaults to all permissions.

The default-permissions setting specifies what permissions are authorized when connecting to an auth token when connecting to nixbuild.net, the default-permissions nixbuild.net without using an auth token. If you are using an auth token this setting will be ignored.

If you don't need the control and flexibility that auth tokens provide, default-permissions offers a simple way to restrict SSH keys to some operations. A typical use case is to only allow a specific SSH key to be used to make administrative changes to your nixbuild.net account. To achieve this, run the following shell commands:

nixbuild.net> settings default-permissions --remove account:read --remove account-write
nixbuild.net> settings default-permissions --ssh-key my-admin-key --add account:read --add account-write

The first command removes the account:read and account:write permissions from the account (that is, all current and future SSH keys). The second command re-adds those permissions to the SSH key with id my-admin-key.

hashed-mirrors

List of URLs, default empty

A list of web servers used by builtins.fetchurl to obtain files by hash. This setting works exactly as the identically named Nix setting.

ignore-cache-failures

Boolean, default false

If ignore-cache-failures is false, any failure in uploading build inputs or outputs to the configured caches will fail the build. If set to true, upload failures will be ignored. Note, if a build is failed due to cache upload issues, this will not happen until after the build has finished. This means that if you fix the cache issue and retry the same build, the already produced build result will be used, instead of running the build again.

impure-env

List of environment variables (key-value pairs), default empty.

The key-value pairs should be comma- or space-separated on the format name=value.

This option corresponds to the Nix option impure-env. If you setup environment variables with this option, they will be available inside the build of fixed-output derivations, if they also are listed in the special attribute impureEnvVars of the derivations.

One use for this is to make secrets available to builds that need to fetch sources from private repositories. Remember, if you configure this setting in the shell (for the whole account or a specific SSH key), the variables will be stored in nixbuild.net. However, if you use the SSH environment to configure impure-env, the variables will not be stored anywhere in nixbuild.net. Using the SSH environment is therefore recommended if you store secrets in impure-env.

Note that the impure-env setting in Nix is experimental and needs the configurable-impure-env feature turned on, but this is not needed for the impure-env setting in nixbuild.net. The nixbuild.net setting works independently of the Nix setting, and if you configure the impure-env setting in Nix, those variables will not be used by builds running in nixbuild.net.

inject-fs-randomness

Boolean, default false

If enabled, the filesystem within the build sandbox will exhibit random behavior. Currently, this will cause directory entries to be read in a random order, but this feature might be expanded in the future to inject more metadata randomness.

This setting is useful for detecting non-determinism in builds (using the repeat and enforce-determinism options in Nix).

keep-builds-running

Boolean, default false

If enabled, active builds will keep running even if you stop your Nix client or in any other way disconnect from nixbuild.net. The builds will keep running until they are done (or fail). If you re-request a build of such a "disconnected build" nixbuild.net will simply wait for the running build to finish and then deliver the resulting build for your new request.

Please note that disconnected builds incur costs in the same way as normal builds.

max-cpu-hours-per-month

Integer, default 2000

This setting defines how many CPU hours your account can use per month. The setting can be used if you want to set an upper limit for your monthly charges.

If you, for whatever reason, haven't been billed for more than one month, the CPU hour limit set will cover the whole period since the last invoice. So when you set this limit you can always be sure that your next invoice will not exceed it (running builds might still cause the limit to be exceeded, see below).

This setting can only be set on the account level or the SSH key level, not through the SSH environment or Nix derivation.

Note, the limit is about your account's total monthly usage. So you can configure a lower (or higher) limit for a specific SSH key, and as soon as the account's total montly usage has passed that limit, you will not be a able to run any new builds with that particular SSH key. It doesn't matter which SSH keys that have generated the usage.

Running builds will not be terminated if the limit is exceeded, only new builds are affected.

reuse-build-failures

Boolean, default true

When enabled, nixbuild.net will not rebuild a derivation that already has failed for your own or any other account. The derivations (and the content hashes of their inputs) must match exactly in order to be re-used. Only non-transient errors will be re-used.

reuse-build-timeouts

Boolean, default false

If enabled, nixbuild.net will check if any previous build (performed by any account) of the exact same derivation took longer time than the timeout specified (by your Nix client) for the new build. If so, nixbuild.net will not run the build, but instead serve back a timed out build status.

sandbox

Possible values: true, relaxed or false. Defaults to true.

This setting corresponds to the Nix setting sandbox. However, in nixbuild.net it is never possible to actually turn off sandboxing in terms of access to files, devices or the Nix store on the builder servers. Builds will always run inside their own virtual machine where they can access no other files than the build inputs specified by the derivation.

In practice, this setting only controls access to network. If this setting is set to true, only fixed-output derivations will be able to access the network. If set to false, all builds will be able access the network. If set to relaxed, only fixed-output derivations and derivations with the attribute __noChroot set to true will have network access. This behaviour is described closer in the documentation of the corresponding setting in Nix.

It is highly recommended to keep this setting on true or relaxed (to be able to opt-in network access for specific builds with __noChroot). Builds that run with network access enabled will not be considered in some cases when nixbuild.net tries to find existing build results that can safely be re-used for new builds. Therefore, setting sandbox to false will slightly limit reusability of your build results. Additionally, having network access enabled also increases the risk of introducing impurities and reproducibility issues in your builds.

signing-key-for-builds

A private Nix signing key, defaults to a unique key auto-generated on account creation.

NOTE: This setting is set to an auto-generated private key, unique for your account. There is no way for users to read out the private key, and if you change this setting, the initial auto-generated key will be lost.

NOTE: By default, the same auto-generated private key is used both for signing-key-for-builds and signing-key-for-uploads. That is, by default your account will use the same key for signing paths that are uploaded to your store and for signing your build outputs.

This setting lets you manage the signing key used for builds on your own, instead of using the key that nixbuild.net auto-generates for your account. You can even use the SSH environment to configure the signing key, which avoids storing your secret key permanently in nixbuild.net. The key will then only be accessible to nixbuild.net during the time your SSH session lasts.

The private key configured in signing-key-for-builds cannot be retrieved. If you for example run settings signing-key-for-builds --show you will only see the corresponding public key. When running settings signing-key-for-builds --set you need to provide the private key, but you should also make sure to keep it stored safely outside nixbuild.net, to avoid losing it.

Before changing this setting it is recommended you first get an understanding for how signing keys are used in Nix and nixbuild.net.

signing-key-for-uploads

A private Nix signing key, defaults to a unique key auto-generated on account creation.

NOTE: This setting is set to an auto-generated private key, unique for your account. There is no way for users to read out the private key, and if you change this setting, the initial auto-generated key will be lost.

NOTE: By default, the same auto-generated private key is used both for signing-key-for-builds and signing-key-for-uploads. That is, by default your account will use the same key for signing paths that are uploaded to your store and for signing your build outputs.

This setting lets you manage the signing key used for uploads on your own, instead of using the key that nixbuild.net auto-generates for your account. You can even use the SSH environment to configure the signing key, which avoids storing your secret key permanently in nixbuild.net. The key will then only be accessible to nixbuild.net during the time your SSH session lasts.

The private key configured in signing-key-for-uploads cannot be retrieved. If you for example run settings signing-key-for-uploads --show you will only see the corresponding public key. When running settings signing-key-for-uploads --set you need to provide the private key, but you should also make sure to keep it stored safely outside nixbuild.net, to avoid losing it.

Before changing this setting it is recommended you first get an understanding for how signing keys are used in Nix and nixbuild.net.

substituters

List of URLs, default https://cache.nixos.org/

Defines the list of substituters nixbuild.net should fetch from when running your builds. To disable substitution, remove all entries of this list. This setting is similar to the identically named Nix setting.

Remember that when adding new substituters you also need to add their public keys using the trusted-public-keys setting. If you don't add the trusted public key of the cache, nixbuild.net will not be able to use any fetched closures in your builds, since it only allows using signed and trusted paths.

nixbuild.net supports substituting from the following kind of substituters:

  • Public HTTP caches
  • Public Cachix caches
  • Private Cachix caches

For public HTTP and Cachix caches, use the substituter's domain name including the HTTP scheme, like https://cache.nixos.org or https://nix-community.cachix.org.

For private Cachix caches, use an URL on the form cachix://my-cache.cachix.org. You must also configure an access token with write permissions, using the access-tokens setting.

This is an example on how to add the nix-community public cache to your list of substituters:

nixbuild.net> settings substituters --add https://nix-community.cachix.org
nixbuild.net> settings trusted-public-keys --add nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=

You can use different substituter lists depending on which SSH key you use or even depending on your SSH environment.

trusted-public-keys

List of public keys, defaults to cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=.

Defines which signing keys you want to trust.

You should usually make sure that the trusted-public-keys matches the substituters you have configured.

You can use different trusted public key lists depending on which SSH key you use or even depending on your SSH environment. This effectively gives you a way to operate on a subset of the paths available to you in nixbuild.net. If a path is signed by a key not listed in your current list of trusted public keys, that path will be invisible to your Nix client.

The key that is used for signing your builds on nixbuild.net is defined by the signing-key-for-builds setting and it is implicitly part of the trusted-public-keys setting. The same is true signing-for-uploads.

The set of trusted public keys defined by this setting, together with the implicit trusted signing keys, are available as a Biscuit fact. This make it possible to include them in custom access policies.

For more information on how signing keys are used in nixbuild.net, see the documentation about signing keys.

settings-from-drv-env

Boolean, default false.

This setting must be set to true in order for Nix derivation configuration to used.

settings-from-ssh-env

Boolean, default true.

This setting must be set to true in order for SSH environment configuration to used.