Skip to content

Configuration and Administration

The Shell does not have a web frontend for administrating your account. Instead all administration and configuration is done through a terminal-based shell accessible over SSH like this:

ssh shell

By default, the SSH key you used when registering is used both for performing Nix builds and for accessing the administration shell. You can, however, add more SSH keys to your account and give the keys different permissions within your account. It doesn't matter what user name you connect with, only your SSH key will be checked. This also means that the same SSH keys can't be added to multiple accounts.

The shell doesn't yet have support for command history or many other features that you could expect from a proper shell. However, you can use the rlwrap program to mitigate this:

rlwrap ssh shell

This will make things like Up/Down arrow keys and CTRL-R work as you would expect.

The greeting screen showed each time you log in to the shell also includes a list of all top-level commands, and instructions on how the help system works:

••••••• •••••••

Welcome to!

This shell allows you to administer your account
and retrieve information about your nix builds.

Account name: bob
Unbilled CPU hours: 0
Free build time left: 49:59:59

Available shell commands:

  help       Show help
  get        Show all account settings
  set        Set an account settings
  unset      Revert an account setting to default
  list       List entities
  show       Show details about entities
  usage      Show resource usage
  ssh-keys   Manage your public SSH keys

Run 'help COMMAND' for help on individual shell commands.
For help on subcommands run 'COMMAND SUBCOMMAND --help'.
For more documentation, see:

Account Usage

To see how much you've been using, run the usage command:> usage

Resources used since 2021-03-01
Build count       : 51
Successful builds : 51
Wall time         : 5.79 s
CPU time          : 6.26 s

The usage metrics only includes non-discarded builds and includes any free build time consumed.
To find out your currently accumulated cost, or see past invoices, use the 'billing info' command.

By default, the usage command will show your usage during the current month. You can also show the previous month's usage with the -l option and the total usage with the -t option:> usage -h
usage - Show resource usage

Usage: usage [(-t|--total) | (-l|--last-month) | (-m|--this-month)]

Available options:
  -t,--total               Show total usage
  -l,--last-month          Show last month's usage
  -m,--this-month          Show this month's usage (default)
  -h,--help                Show this help text

To get information on how much money you've spent on builds, use the billing commands.


You can get and set settings with the get and set commands.

Show all settings by just running get:> get
Account Settings

cache-build-failures  true
cache-build-timeouts  false
keep-builds-running   false
always-substitute     false
never-substitute      false

Settings overrides from your SSH client environment are not
included above.

Set individual settings with set:> set keep-builds-running true> get
Account Settings

cache-build-failures  true
cache-build-timeouts  false
keep-builds-running   true
always-substitute     false
never-substitute      false

Settings overrides from your SSH client environment are not
included above.

You can revert account settings back to default with unset:> unset keep-builds-running

SSH Keys

You can list, add and remove ssh keys associated with your account using the ssh-keys command:

ssh-keys - Manage your public SSH keys

Usage: ssh-keys SUBCOMMAND

Available options:
  -h,--help                Show this help text

Available subcommands:
  list                     List SSH keys
  add                      Add a key
  remove                   Remove a key
  get                      Get settings overrides for an SSH key
  set                      Set settings overrides for an SSH key
  unset                    Unset settings overrides for an SSH key

Binary Caches supports fetching build dependencies from binary caches. This can make builds a lot faster, especially if your network upload speed is poor.

To activate substitution from binary caches you must use the Nix option builders-use-substitutes or enable the always-substitute setting.

By default, is used when looks for substitutions, but you can add or remove caches to your account. Currently, there is no UI for editing the list of caches, but if you contact [email protected] you'll be assisted. Also Cachix caches can be added.

Note, that path substitution can happen even though the builders-use-substitutes option hasn't been activated. If another user has triggered substitution previously, and your build depends on any of the substituted paths, they will be used directly. Only paths that come from a substituter that is trusted by your account will be used. Nix public-key signatures are used to validate paths downloaded from substituters. Unsigned paths are not used.

Using as a substituter

You can set up Nix to use as a substituter. This can improve performance in some situtations, and it is very useful in custom CI setups where you want to integrate Note that even if you set up as a substituter, you still need to use an SSH key to access it.

To set up as a substituter, first fetch your public signing key through the shell:> signing-keys account-keys

Then add the substituter and signing key to your existing configuration in nix.conf:

substituters = ... ssh://
trusted-public-keys = ...

You can use trusted-substituters instead of substituters to not use as a substituter by default, but make it available for selection on the command line.


The billing commands let you manage billing for your account:> billing --help
billing - Billing activation and info

Usage: billing SUBCOMMAND

Available options:
  -h,--help                Show this help text

Available subcommands:
  activate                 Enable non-free usage
  edit                     Edit your credit card details
  info                     Display billing details

To be able to use beyond the initial free build hours you need to enable billing by running billing activate. You can do this at any time, and as soon as you've done it your account will be able to run non-free builds. If you run out of free build hours before you have activated billing, you will not be able to run any more builds. As soon as you activate billing, you will be able to run builds again.

When activating billing, you will be directed to a Stripe-hosted web page where you can enter your billing address and credit card details. When running billing activate you need to provide your company name or full name (for personal accounts) like this:> billing activate Acme LLC

Billing has been activated for your account.
You will now be able to use beyond your free CPU hours.
If you still have free CPU hours left, you will not be charged until they have been used up.

IMPORTANT: Visit the time-limited url below to enter your credit card details and billing address.

If you want to change your payment method after the above url has expired, use the command 'billing edit'.
If you need to make any other billing changes, please contact [email protected]
If you fail to provide valid billing details your account may be locked.

If you need to change your credit card details at any time, you can use the billing edit command. If you need to change any other billing details, you must contact [email protected].

The billing info command lets you see the amount of the upcoming invoice, as well as past invoices.

List Builds

Use the command list builds -r to list your currently running builds:> list builds -r
70196 2020-08-23 21:05:10Z 3.21 s 1 CPU [In queue]

70195 2020-08-23 21:05:10Z 3.66 s 1 CPU [In queue]

70194 2020-08-23 21:05:09Z 3.40 s 4 CPUs [Running]

70193 2020-08-23 21:05:08Z 4.18 s 2 CPUs [Running]

Remove the -r option to also show historic builds. By default, at most 500 builds are listed, but that can be adjusted with the -l option.