Skip to content

First Steps with CtrlOS

This section explains common first steps to using CtrlOS in your project.

Using CtrlOS

The initial step to using CtrlOS is to fetch the sources as tarball via your NixOS channel or as a Flake input. As access to the tarball is authenticated, you need to configure an access token in your .netrc file. See nix.conf and .netrc for more details.

In nix.conf, specify the location of your .netrc file as an absolute path. For example, to have a separate .netrc file only for Nix you can place it in the Nix configuration directory:

netrc-file = /home/youruser/.config/nix/netrc

In the file specified in netrc-file, add:

machine channels.ctrl-os.com
password YOURTOKEN

Access tokens are currently provided by your contact at Cyberus.

Note

Access tokens must be configured via .netrc and not via the access-tokens configuration in nix.conf. The latter will not work.

As a Channel

Once you have configured authentication, you can add a specific CtrlOS version as a channel. To add CtrlOS as your main NixOS channel, point the nixos channel to a specific CtrlOS release:

$ nix-channel --add https://channels.ctrl-os.com/channel/ctrlos-24.05.tar.xz nixos
$ nix-channel --update

As a Flake Input

Similarly to channels, you can use CtrlOS as a Flake input. Typically, the nixpkgs input points to the CtrlOS tarball:

{
  description = "A Very Basic CtrlOS Flake";

  inputs = {
    # Use the CtrlOS source as nixpkgs input.
    nixpkgs.url = "https://channels.ctrl-os.com/channel/ctrlos-24.05.tar.xz";
  };

  outputs = { self, nixpkgs }: {
    packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
    packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
  };
}

Available Versions

The following versions are available for CtrlOS:

Version Status End of Life
ctrlos-24.05 Preview May 2029

Binary Cache

Cyberus Technology maintains a binary cache, which contains pre-built software for each CtrlOS version. We recommend using the binary cache if you use CtrlOS, because you won't have to recompile software that our internal CI has already built.

Configuring the Binary Cache

To configure the binary cache, add it as one of the substituters and add the corresponding public key.

extra-substituters = https://cache.ctrl-os.com/
extra-trusted-public-keys = ctrl-os:baPzGxj33zp/P+GAIJXsr8ss9Law+qEEFViX1+flbv8=

In your .netrc file (see above), add the following:

machine cache.ctrl-os.com
password YOURTOKEN

Similar to the channel, access tokens are currently provided by your contact at Cyberus. The same token can be used for both the channel and the cache.