Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

_module.args

Additional arguments passed to each module in addition to ones like lib, config, and pkgs, modulesPath.

This option is also available to all submodules. Submodules do not inherit args from their parent module, nor do they provide args to their parent module or sibling submodules. The sole exception to this is the argument name which is provided by parent modules to a submodule and contains the attribute name the submodule is bound to, or a unique generated name if it is not bound to an attribute.

Some arguments are already passed by default, of which the following cannot be changed with this option:

  • lib: The nixpkgs library.

  • config: The results of all options after merging the values from all modules together.

  • options: The options declared in all modules.

  • specialArgs: The specialArgs argument passed to evalModules.

  • All attributes of specialArgs

    Whereas option values can generally depend on other option values thanks to laziness, this does not apply to imports, which must be computed statically before anything else.

    For this reason, callers of the module system can provide specialArgs which are available during import resolution.

    For NixOS, specialArgs includes modulesPath, which allows you to import extra modules from the nixpkgs package tree without having to somehow make the module aware of the location of the nixpkgs or NixOS directories.

    { modulesPath, ... }: {
  imports = [
    (modulesPath + "/profiles/minimal.nix")
  ];
}

For NixOS, the default value for this option includes at least this argument:

  • pkgs: The nixpkgs package set according to the nixpkgs.pkgs option.

Type: lazy attribute set of raw value

Declared by:

age

The agenix configuration for the container’s user environment.

This module is a port of agenix to nix2gpu, and allows simplified management of age encrypted secrets in nix.

To use this, you must first enable the optional agenix integration:

Then enable the module with:

age.enable = true;

Type: submodule

Default: { }

Declared by:

age.enable

Whether to enable enable agenix integration.

Type: boolean

Default: false

Example: true

Declared by:

age.package

The rage package to use.

Type: package

Default: pkgs.rage

Declared by:

age.identityPaths

Paths to SSH keys to be used as identities in age decryption.

Type: list of absolute path

Default:

[
  "/etc/ssh/ssh_host_rsa_key"
  "/etc/ssh/ssh_host_ed25519_key"
]

Declared by:

age.secrets

Attrset of secrets.

Type: attribute set of (submodule)

Default: { }

Declared by:

age.secrets.<name>.file

Age file the secret is loaded from.

Type: absolute path

Declared by:

age.secrets.<name>.mode

Permissions mode of the decrypted secret in a format understood by chmod.

Type: string

Default: "0400"

Declared by:

age.secrets.<name>.name

Name of the file used in ${cfg.secretsDir}

Type: string

Default: "‹name›"

Declared by:

age.secrets.<name>.path

Path where the decrypted secret is installed.

Type: string

Default: "\${XDG_RUNTIME_DIR}/agenix/‹name›"

Declared by:

Whether to enable symlinking secrets to their destination.

Type: boolean

Default: true

Example: true

Declared by:

age.secretsDir

Folder where secrets are symlinked to

Type: string

Default:

"${XDG_RUNTIME_DIR}"/${dir}.

Declared by:

age.secretsMountPoint

Where secrets are created before they are symlinked to ${cfg.secretsDir}

Type: unspecified value

Default:

"${XDG_RUNTIME_DIR}"/${dir}.

Declared by:

copyToRoot

A list of packages to be copied to the root of the container.

This option allows you to specify a list of Nix packages that will be symlinked into the root directory of the container. This is useful for making essential packages and profiles available at the top level of the container’s filesystem.

The default value includes the base system, the container’s profile, and the Nix store profile, which are essential for the container to function correctly.

If you want to add extra packages without replacing the default set, use the extraCopyToRoot option instead.

This is a direct mapping to the copyToRoot attribute from nix2container.

Type: list of package

Default: The generated base system from the other config options

Example:

copyToRoot = with pkgs; [
  coreutils
  git
];

Declared by:

cuda.enable

If nix2gpu’s cuda integration should be enabled or not

Type: boolean

Default: true

Example:

cudaPackages = pkgs.cudaPackages_11_8;

Declared by:

cuda.packages

The set of CUDA packages to be used in the container.

This option allows you to select a specific version of the CUDA toolkit to be installed in the container. This is crucial for ensuring compatibility with applications and machine learning frameworks that depend on a particular CUDA version.

The value should be a package set from pkgs.cudaPackages. You can find available versions by searching for cudaPackages in Nixpkgs.

Type: package

Default: pkgs.cudaPackages_13_0

Example:

cuda.packages = pkgs.cudaPackages_11_8;

Declared by:

env

A list of environment variables to set inside the container.

This option allows you to define the environment variables that will be available within the container.

The default value provides a comprehensive set of environment variables for a typical development environment, including paths for Nix, CUDA, and other essential tools.

If you want to add extra environment variables without replacing the default set, use the extraEnv option instead.

This is a direct mapping to the Env attribute of the oci container spec.

Type: attribute set of string

Default:

CURL_CA_BUNDLE = "/etc/ssl/certs/ca-bundle.crt";
HOME = "/root";
LANG = "en_US.UTF-8";
LC_ALL = "en_US.UTF-8";
LD_LIBRARY_PATH = "/lib/x86_64-linux-gnu:/usr/lib64:/usr/lib";
LOCALE_ARCHIVE = "glibc/lib/locale/locale-archive";
NIXPKGS_ALLOW_UNFREE = "1";
NIX_PATH = "nixpkgs=/nix/var/nix/profiles/per-user/root/channels";
NIX_SSL_CERT_FILE = "/etc/ssl/certs/ca-bundle.crt";
PATH = "/root/.nix-profile/bin:/nix/var/nix/profiles/default/bin:/usr/local/nvidia/bin:/usr/local/cuda/bin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
SSL_CERT_FILE = "/etc/ssl/certs/ca-bundle.crt";
TERM = "xterm-256color";
USER = "root";

Example:

env = {
  MY_CUSTOM_VARIABLE = "hello";
  ANOTHER_VARIABLE = "world";
};

Declared by:

exposedPorts

A set of ports to expose from the container.

This option allows you to specify which network ports should be exposed by the container. The keys are the port and protocol (e.g., “80/tcp”), and the values are empty attribute sets.

By default, port 22 is exposed for SSH access.

This is a direct mapping to the ExposedPorts attribute of the oci container spec.

Type: attribute set of anything

Default:

{
  "22/tcp" = { };
}

Example:

exposedPorts = {
  "8080/tcp" = {};
  "443/tcp" = {};
};

Declared by:

extraEnv

A list of extra environment variables to set inside the container.

This option allows you to add more environment variables to the env option without overriding the default set. The variables listed here will be appended to the main env list.

This is the recommended way to add your own custom environment variables.

Type: attribute set of string

Default: { }

Example:

extraEnv = {
  DATABASE_URL = "postgres://user:password@host:port/db";
  NIXPKGS_ALLOW_UNFREE = "1";
};

Declared by:

extraLabels

A set of extra labels to apply to the container.

This option allows you to add custom metadata to the container in the form of labels. These labels can be used for organizing and filtering containers, or for storing information about the container’s contents or purpose.

The labels defined here will be merged with the default labels set.

This is the recommended way to add more labels to your project rather than overriding labels.

Type: attribute set of string

Default: { }

Example:

extraLabels = {
  "com.example.vendor" = "My Company";
  "com.example.project" = "My Project";
};

Declared by:

extraStartupScript

A string of shell commands to be executed at the end of the container’s startup script.

This option provides a way to run custom commands every time the container starts. The contents of this option will be appended to the main startup script, after the default startup tasks have been completed.

This is useful for tasks such as starting services, running background processes, or printing diagnostic information.

Type: string (concatenated when merged)

Default: ""

Example:

extraStartupScript = ''
  echo "Hello world"
'';

Declared by:

home

The home-manager configuration for the container’s user environment.

This option allows you to define the user’s home environment using home-manager. You can configure everything from shell aliases and environment variables to user services and application settings.

By default, a minimal set of useful modern shell packages is included to provide a comfortable and secure hacking environment on your machines.

home-manager is bundled with nix2gpu, so no additional flake inputs are required to use this option.

Type: lazy attribute set of raw value

Default: A sample home manager config with some nice defaults from nix2gpu

Example:

home = home-manager.lib.homeManagerConfiguration {
  inherit pkgs;
  extraSpecialArgs = { inherit inputs; };
  modules = [
    ./home
  ];
};

Declared by:

labels

A set of labels to apply to the container.

This option allows you to define metadata for the container in the form of labels. These labels can be used for organizing and filtering containers, or for storing information about the container’s contents or purpose.

The default value includes several labels that provide information about the container’s origin, runtime, and dependencies.

If you want to add extra labels without replacing the default set, use the extraLabels option instead.

This is a direct mapping to the Labels attribute of the oci container spec.

Type: attribute set of string

Default:

"ai.vast.gpu" = "required";
"ai.vast.runtime" = "nix2gpu";
"org.opencontainers.image.source" = "https://github.com/weyl-ai/nix2gpu";
"org.opencontainers.image.description" = "Nix-based GPU container";

Example:

labels = {
  "my.custom.label" = "some-value";
  "another.label" = "another-value";
};

Declared by:

maxLayers

The maximum number of layers to use when creating the container image.

This option sets the upper limit on the number of layers that will be used to build the container image. This is an important consideration for caching and build time purposes, and can have many benefits.

See this blog post for some nice information on layers in a nix context.

This is a direct mapping to the maxLayers attribute from nix2container.

Type: signed integer

Default: 50

Example:

maxLayers = 100;

Declared by:

meta

meta attributes to include in the output of generated nix2gpu containers

Type: lazy attribute set of raw value

Default: { }

Example:

{
  meta = {
    description = "My cool nimi package";
  };
}

Declared by:

nimiSettings

Bindings to nimi.settings for this nix2gpu instance.

Use this to tune Nimi runtime behavior (restart policy, logging, startup hooks, and container build settings) beyond the defaults provided by nix2gpu.

Type: module

Default: { }

Declared by:

nixConfig

The content of the nix.conf file to be used inside the container.

This option allows you to provide a custom nix.conf configuration for the Nix daemon running inside the container. This can be used to configure things like custom binary caches, experimental features, or other Nix-related settings.

By default, a standard nix.conf is provided which is suitable for most use cases.

Type: string

Default:

sandbox = false
build-users-group =
experimental-features = nix-command flakes
trusted-users = root
max-jobs = auto
cores = 0
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs= cuda-maintainers.cachix.org-1:0dq3bujKpuEPMCX6U4WylrUDZ9JyUG0VpVZa7CNfq5E= cache.garnix.io:CTFPyKSLcx5RMJKfLo5EEPUObbA78b0YQ2DTCJXqr9g=
substituters = https://cache.nixos.org https://nix-community.cachix.org https://cuda-maintainers.cachix.org https://cache.garnix.io
keep-outputs = true
keep-derivations = true
accept-flake-config = true

Example:

nixConfig = ''
  experimental-features = nix-command flakes
  substituters = https://cache.nixos.org/ https://my-cache.example.org
  trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= my-cache.example.org-1:abcdef...
'';

Declared by:

passthru

passthru attributes to include in the output of generated nix2gpu containers

Type: lazy attribute set of raw value

Default: { }

Example:

{
  passthru = {
    doXYZ = pkgs.writeShellApplication {
      name = "xyz-doer";
      text = ''
        xyz
      '';
    };
  };
}

Declared by:

registries

The container registries to push your images to.

This option specifies a list of the full registry paths, including the repository and image name, where the container image will be pushed. This is a mandatory field if you intend to publish your images via <container>.copyToGithub.

Type: list of string

Default: [ ]

Example:

registries = [ "ghcr.io/my-org/my-image" ];

Declared by:

services

Services to run inside the nix2gpu container via Nimi.

Each attribute defines a named NixOS modular service (Nix 25.11): import a service module and override its options per instance. This keeps service definitions composable and reusable across projects.

For the upstream model, see the NixOS manual section on Modular Services.

Type: lazy attribute set of module

Default: { }

Declared by:

sshdConfig

The content of the sshd_config file to be used inside the container.

This option allows you to provide a custom configuration for the OpenSSH daemon (sshd) running inside the container. This can be used to customize security settings, authentication methods, and other SSH-related options.

By default, a standard sshd_config is provided that is suitable for most use cases, with password authentication disabled in favor of public key authentication.

Type: string

Default: nix2gpu generated sshd config

Example:

sshdConfig = builtins.readFile ./my-sshd-config;

Declared by:

systemPackages

A list of system packages to be copied into the container.

This option allows you to specify a list of Nix packages that will be added to the container.

Type: list of package

Default: [ ]

Example:

systemPackages = with pkgs; [
  coreutils
  git
];

Declared by:

tag

The tag to use for your container image.

This option specifies the tag that will be applied to the container image when it is built and pushed to a registry. Tags are used to version and identify different builds of your image.

The default value is “latest”, which is a common convention for the most recent build. However, it is highly recommended to use more descriptive tags for production images, such as version numbers or git commit hashes.

Type: string

Default: "latest"

Example:

tag = "v1.2.3";

Declared by:

tailscale

The tailscale configuration to use for your nix2gpu container.

Configure the tailscale daemon to run on your nix2gpu instance, giving your instances easy and secure connectivity.

Type: submodule

Default: { }

Example:

tailscale = {
  enable = true;
};

Declared by:

tailscale.enable

Whether to enable enable the tailscale daemon.

Type: boolean

Default: false

Example: true

Declared by:

tailscale.authKey

Runtime path to valid tailscale auth key

Type: string

Default: ""

Example: /etc/default/tailscaled

Declared by:

user

The default user for the container.

This option specifies the username of the user that will be used by default when running commands or starting services in the container.

The default value is “root”. While this is convenient for development, it is strongly recommended to create and use a non-root user for production environments to improve security. You can create users and groups using the users and groups options in your home-manager configuration.

Type: string

Default: root

Example:

user = "appuser";

Declared by:

workingDir

The working directory for the container.

This option specifies the directory that will be used as the current working directory when the container starts. It is the directory where commands will be executed by default.

The default value is “/root”. You may want to change this to a more appropriate directory for your application, such as /app or /srv.

Type: string

Default: /root

Example:

workingDir = "/app";

Declared by: