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):

System configuration (default settings) — Not configurable by the end user.
Account configuration — Settings that are used for all users of the same account. Configurable by end users through the nixbuild.net shell.
SSH key configuration — Settings that are used for a specific SSH key. Configurable by end users through the nixbuild.net shell.
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.
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.
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 by nixbuild.net to access private resources on your behalf. This works much in the same way as the identically named Nix setting.

These types of access tokens are supported:

s3: Used when uploading store paths directly from nixbuild.net to an S3 bucket (see the caches setting), or when using an S3 bucket as substituter.
cachix: Used when uploading store paths directly from nixbuild.net to Cachix (see the caches setting), or when using private Cachix caches as substituters. Only Cachix per-cache auth tokens are supported, not personal auth tokens (see the Cachix documentation for more information).
netrc: These tokens are used by pkgs.stdenv.fetchurlBoot and <nix/fetchurl.nix> to fetch from authenticated servers. Adding netrc tokens to the access-tokens setting has the same effect as adding the tokens to a .netrc file and configuring the Nix setting netrc-file to point to that file in a setup that doesn't use nixbuild.net. You can see the NixOS Wiki for more information about netrc usage.

You can configure the access-tokens settings with multiple access tokens of different types. nixbuild.net will decide what token to use based on the context and the host name specified in the token definition. See below for the syntax to use for each type of token.

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.

S3 tokens¶

S3 access tokens are specified like this:

s3://<BUCKET>/<PREFIX>=<ACCESS KEY ID>:<SECRET ACCESS KEY>

When adding an S3 cache or substituter, you should set up an S3 access token with a matching bucket and prefix (if any).

AWS session tokens are also supported. Use the following syntax to add an S3 access token with a a session token:

s3://<BUCKET>/<PREFIX>=<ACCESS KEY ID>:<SECRET ACCESS KEY>:<SESSION TOKEN>

Cachix tokens¶

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:

netrc tokens¶

netrc uses the terminology machine, login and password to represent host address, username and password. See the curl documentation for more information.

In nixbuild.net, netrc tokens are formatted like this:

netrc://login:password@machine

netrc also allows for password-only auth (no user name sent to the server). Such tokens are formatted like this:

netrc://password@machine

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.

S3 Caches¶

To make nixbuild.net upload store paths to an S3 bucket, add a cache using the following syntax:

s3://<BUCKET>/<PREFIX>?region=<REGION>

The path prefix is optional. If used, narinfo-files and nar-files will be stored in the specified prefix ("subdirectory") in the S3 bucket. Multiple caches can use the same bucket, if they use different prefixes. access-tokens should be added per bucket+prefix combination.

S3 caches support a few settings. The settings are added as an URL query string, like this:

s3://my-bucket?setting1=value1&setting2=value2&...

The available settings are:

addressing-style: If you are configuring the S3 endpoint (see below) explicitly, you can set the addressing style to match your S3 provider. The addressing style can be set to auto, path or virtual.
endpoint: If you are using some S3 provider other than AWS, like Google Cloud Storage or Minio, you can use endpoint to point nixbuild.net to the correct S3 server.
path-info-cache-ttl-seconds: The maximum time nixbuild.net will remeber narinfo entries, defaults to 3600 seconds. When nixbuild.net is about to upload a path to an S3 bucket, it will first check if there already exists a narinfo file in the location it would upload to. If there is a narinfo file there, no upload will happen (neither narinfo nor nar contents). nixbuild.net will then remember the fact that the narinfo exists remotely.
region: Sets the region of the bucket, like us-east-1 or eu-north-1. It is important to always set this parameter so that nixbuild.net picks the correct bucket endpoint.
secret-key: The secret signing key that should be used for signing all paths uploaded to the S3 bucket. If not defined, paths will not be signed when uploaded.

Here is an example of using the NixBuild shell to add an S3 cache:

nixbuild.net> settings caches --add s3://my-test-cache?region=eu-north-1
nixbuild.net> settings access-tokens --add s3://my-test-cache=AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

You could add an additional cache that uses a subdirectory in the same bucket:

nixbuild.net> settings caches --add s3://my-test-cache/cache01?region=eu-north-1
nixbuild.net> settings access-tokens --add s3://my-test-cache/cache01=AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Cachix Caches¶

For Cachix, 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 should run:

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

Cachix access tokens can have write permissions or be read-only. If you add both kinds of tokens for the same Cachix cache, nixbuild.net will automatically use the write token when performing uploads to that cache.

default-cpu¶

Integer, default 2.

The default number of CPUs nixbuild.net allocates a build, if no historic data can be found for the build. Please note that the settings max-cpu and min-cpu will be taken into account no matter what default-cpu is set to.

default-mem-per-cpu¶

Integer, default 3500.

The default amount of memory, in megabytes (MB), that nixbuild.net allocates a build, if no historic data can be found for the build. The number configured in default-mem-per-cpu will be multiplied with the number of CPUs allocated for the build to come up with the total amount of memory. Please note that the settings max-mem and min-mem will be taken into account no matter what default-mem-per-cpu is set to.

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-build-restarts¶

Integer, default 5.

If nixbuild.net detects that a build fails due to a transient error, or running out of memory, the build will be restarted automatically, possibly with more memory allocated. This setting can be used to limit the number of restarts that are attempted for a single build.

max-cpu¶

Integer, default no limit.

Specifies the maximum number of CPUs to assign to builds. nixbuild.net uses historic data to figure out how many CPUs to allocate for a build. The max-cpu setting puts an upper bound on the number that nixbuild.net comes up with. Please note that the actual upper bound used may be lower due to system limits. The system limits can vary depening on which platform your build uses (Arm or x86_64), and what features the build uses.

If you want to disable the automatic CPU allocation in nixbuild.net, you can set both min-cpu and max-cpu to the same number of CPUs.

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.

max-mem¶

Integer, default no limit.

Specifies the maximum amount of memory, in megabytes (MB), to assign to builds. nixbuild.net uses historic data to figure out how much memory to allocate for a build. The max-mem setting puts an upper bound on the number that nixbuild.net comes up with. Please note that the actual upper bound used may be lower due to system limits. The system limits can vary depening on which platform your build uses (Arm or x86_64), and what features the build uses.

If you want to disable the automatic memory allocation in nixbuild.net, you can set both min-mem and max-mem to the same number.

max-silent-time¶

Integer, default 21600 seconds (6 hours)

Sets the maximum time (in seconds) that a build is allowed to be silent. Works just like the identically named Nix setting.

min-cpu¶

Integer, default 1.

Specifies the minimum number of CPUs to assign to builds. nixbuild.net uses historic data to figure out how many CPUs to allocate for a build. The min-cpu setting puts a lower bound on the number that nixbuild.net comes up with.

If you want to disable the automatic CPU allocation in nixbuild.net, you can set both min-cpu and max-cpu to the same number of CPUs.

min-mem¶

Integer, default no limit.

Specifies the minimum amount of memory, in megabytes (MB), to assign to builds. nixbuild.net uses historic data to figure out how much memory to allocate for a build. The min-mem setting puts a lower bound on the number that nixbuild.net comes up with.

If you want to disable the automatic memory allocation in nixbuild.net, you can set both min-mem and max-mem to the same number.

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.

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.

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

Public HTTP caches
Public Cachix caches
Private Cachix caches
Private S3 buckets (AWS S3 or compatible providers)

HTTP Substituters¶

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

S3 Substituters¶

To make nixbuild.net substitute store paths from an S3 bucket, add a substituter using the following syntax:

s3://<BUCKET>/<PREFIX>

The path prefix is optional. If used, narinfo-files and nar-files will be searched for in the specified prefix ("subdirectory") within the S3 bucket. Multiple substituters can use the same bucket, if they use different prefixes. access-tokens should be added per bucket+prefix combination.

S3 substituters support a few settings. The settings are added as an URL query string, like this:

s3://my-bucket?setting1=value1&setting2=value2&...

The available settings are:

addressing-style: If you are configuring the S3 endpoint (see below) explicitly, you can set the addressing style to match your S3 provider. The addressing style can be set to auto, path or virtual.
endpoint: If you are using some S3 provider other than AWS, like Google Cloud Storage or Minio, you can use endpoint to point nixbuild.net to the correct S3 server.
region: Sets the region of the bucket. It is preferable to always set this parameter when using AWS S3 buckets. This avoids an extra redirect that will happen if the bucket is not located in us-east-1.
require-sigs: Can be set to true or false, defaults to true. If true, nixbuild.net will only download store paths from the substituter if there are valid signatures in the corresponding narfinfo files, created by a signing key available in trusted-public-keys. If false, signatures are not required. Instead, any downloaded paths will be automatically signed by the key defined in signing-key-for-uploads.

Here is an example of using the NixBuild shell to add an S3 substituter:

nixbuild.net> settings substituters --add s3://my-test-cache?region=eu-north-1&require-sigs=false
nixbuild.net> settings access-tokens --add s3://my-test-cache=AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Cachix Substituters¶

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.

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.

timeout¶

Integer, default 43200 seconds (12 hours)

Sets the build timeout in seconds. Works just like the identically named Nix setting. You can override this setting with the --timeout option in your Nix client, but only if you use the ssh:// protocol when using nixbuild.net, not ssh-ng://.