_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: ThespecialArgsargument passed toevalModules. -
All attributes of
specialArgsWhereas 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
specialArgswhich are available during import resolution.For NixOS,
specialArgsincludesmodulesPath, which allows you to import extra modules from the nixpkgs package tree without having to somehow make the module aware of the location of thenixpkgsor 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 thenixpkgs.pkgsoption.
Type: lazy attribute set of raw value
Declared by:
assertions.*.assertion
Assertion to evaluate and check.
Type: boolean
Declared by:
assertions.*.message
Message to print on assertion failure.
Type: string
Declared by:
meta
meta attributes to
include in the output of generated Nimi packages
Type: lazy attribute set of raw value
Default:
{ }
Example:
{
meta = {
description = "My cool nimi package";
};
}
Declared by:
passthru
passthru attributes to
include in the output of generated Nimi packages
Type: lazy attribute set of raw value
Default:
{ }
Example:
{
passthru = {
doXYZ = pkgs.writeShellApplication {
name = "xyz-doer";
text = ''
xyz
'';
};
};
}
Declared by:
services
Services to run inside the nimi runtime.
Each attribute defines a named modular service: a reusable, composable module that you can import, extend, and tailor for each instance. This gives you clear service boundaries, easy reuse across projects, and a consistent way to describe how each process should run.
The services option is an lazyAttrsOf submodule: the attribute name is
the service name, and the module content defines its behavior. You
typically provide a service by importing a module from a package and
then overriding or extending its options.
For the full upstream explanation and portability model, see the NixOS manual section on Modular Services.
Type: lazy attribute set of (submodule)
Default:
{ }
Example:
{
services."ghostunnel-plain-old" = {
imports = [ pkgs.ghostunnel.services.default ];
ghostunnel = {
listen = "0.0.0.0:443";
cert = "/root/service-cert.pem";
key = "/root/service-key.pem";
disableAuthentication = true;
target = "backend:80";
unsafeTarget = true;
};
};
services."ghostunnel-client-cert" = {
imports = [ pkgs.ghostunnel.services.default ];
ghostunnel = {
listen = "0.0.0.0:1443";
cert = "/root/service-cert.pem";
key = "/root/service-key.pem";
cacert = "/root/ca.pem";
target = "backend:80";
allowCN = [ "client" ];
unsafeTarget = true;
};
};
}
Declared by:
services.<name>.configData
Configuration data files for the service
These files are made available to the service and can be updated without restarting the service process, enabling configuration reloading.
The service manager implementation determines how these files are exposed to the service (e.g., via a specific directory path).
This path is available in the path sub-option for each configData.<name> entry.
This is particularly useful for services that support configuration reloading via signals (e.g., SIGHUP) or which pick up changes automatically, so that no downtime is required in order to reload the service.
Type: lazy attribute set of (submodule)
Default:
{ }
Example:
{
"server.conf" = {
text = ''
port = 8080
workers = 4
'';
};
"ssl/cert.pem" = {
source = ./cert.pem;
};
}
Declared by:
services.<name>.configData.<name>.enable
Whether this configuration file should be generated. This option allows specific configuration files to be disabled.
Type: boolean
Default:
true
Declared by:
services.<name>.configData.<name>.name
Name of the configuration file (relative to the service’s configuration directory). Defaults to the attribute name.
Type: string
Declared by:
services.<name>.configData.<name>.path
The actual path where this configuration file will be available. This is determined by the service manager implementation.
On NixOS it is an absolute path. Other service managers may provide a relative path, in order to be unprivileged and/or relocatable.
Type: string (read only)
Declared by:
services.<name>.configData.<name>.source
Path of the source file.
Type: absolute path
Declared by:
services.<name>.configData.<name>.text
Text content of the configuration file.
Type: null or strings concatenated with “\n”
Default:
null
Declared by:
services.<name>.meta.maintainers
List of maintainers of each module. This option should be defined at most once per module.
The option value is not a list of maintainers, but an attribute set that maps module file names to lists of maintainers.
Type: list of (maintainer)
Default:
[ ]
Example:
[ lib.maintainers.alice lib.maintainers.bob ]
Declared by:
services.<name>.process.argv
Command filename and arguments for starting this service.
This is a raw command-line that should not contain any shell escaping.
If expansion of environmental variables is required then use
a shell script or importas from pkgs.execline.
Type: list of (string or absolute path convertible to it)
Example:
[ (lib.getExe config.package) "--nobackground" ]
Declared by:
services.<name>.services
A collection of modular services that are configured in one go.
You could consider the sub-service relationship to be an ownership relation. It does not automatically create any other relationship between services (e.g. systemd slices), unless perhaps such a behavior is explicitly defined and enabled in another option.
Type: attribute set of (submodule)
Default:
{ }
Declared by:
settings.binName
Name of the binary to generate with your nimi wrapper.
Changes the name of the default generated binary name from “nimi” to whatever you select.
Type: string
Default:
"nimi"
Example:
{
settings.binName = "my-awesome-service-runner";
}
Declared by:
settings.container
Configures nimi’s builtin container generation.
Note that none of these options will have any effect unless you are using
nimi.mkContainerImage to build your containers.
These are mappings to nix2container’s buildImage function, please
check there for further documentation.
Type: submodule
Default:
{ }
Declared by:
settings.container.copyToRoot
A derivation (or list of derivations) copied in the image root directory
(store path prefixes /nix/store/hash-path are removed,
in order to relocate them at the image /).
pkgs.buildEnv can be used to build a derivation which has to
be copied to the image root. For instance, to get bash and
coreutils in the image /bin:
Type: (list of path in the Nix store) or path in the Nix store convertible to it
Default:
[ ]
Declared by:
settings.container.fromImage
An image that is used as base image of this image;
Use nix2container.pullImage or nix2container.pullImageFromManifest to supply this.
Type: null or path in the Nix store
Default:
null
Declared by:
settings.container.imageConfig
An attribute set describing an image configuration as defined in the OCI image specification.
Type: open submodule of lazy attribute set of anything
Default:
{ }
Declared by:
settings.container.initializeNixDatabase
To initialize the Nix database with all store paths added into the image.
Note this is only useful to run nix commands from the image, for instance to build an image used by a CI to run Nix builds.
Type: boolean
Default:
false
Declared by:
settings.container.layers
A list of layers built with the nix2container.buildLayer function.
If a store path in deps or contents belongs to one of these layers, this store path is skipped.
This is pretty useful to isolate store paths that are often updated from more stable store paths, to speed up build and push time.
Type: list of path in the Nix store
Default:
[ ]
Declared by:
settings.container.maxLayers
The maximum number of layers to create.
This is based on the store path “popularity” as described in this blog post.
Note this is applied on the image layers and not on layers added with the buildImage.layers attribute.
Type: positive integer, meaning >0
Default:
1
Declared by:
settings.container.name
The name of the generated image
Type: string
Default:
"nimi-container"
Declared by:
settings.container.perms
A list of file permisssions which are set when the tar layer is created: these permissions are not written to the Nix store.
Type: list of (submodule)
Default:
[ ]
Declared by:
settings.container.tag
The tag for the generated image to use
Type: string
Default:
"latest"
Declared by:
settings.logging
Logging behavior for the nimi process manager.
This section controls if per-service log files are written during a run. When enabled, each service writes to its own file under the configured logs directory.
Log files are created at runtime and live in a run-specific subdirectory
under logsDir (for example logs-0/service-a.txt). Each line from the
service stdout or stderr is appended to the same file, preserving
execution order as best as possible.
Type: submodule
Default:
{ }
Example:
{
enable = true;
logsDir = "my_logs";
}
Declared by:
settings.logging.enable
Whether to enable If per-service log files should be written to settings.logging.logsDir.
When disabled, log output still streams to stdout/stderr but no files are created. .
Type: boolean
Default:
false
Example:
true
Declared by:
settings.logging.logsDir
Directory to create and write per-service logs to.
Nimi creates a logs-<n> subdirectory inside this path at runtime
and writes one file per service.
Type: string
Default:
"nimi_logs"
Declared by:
settings.restart
Restart policy for the nimi process manager.
Use this to control if and how services are restarted after they exit. This is the main safety net for keeping long-running services alive, and also a guardrail to prevent tight restart loops from burning CPU.
You can choose a policy that matches the reliability needs of each deployment. For development you might disable restarts entirely, while production workloads usually benefit from a bounded or always-on policy.
Type: submodule
Default:
{ }
Example:
{
mode = "up-to-count";
time = 500;
count = 3;
}
Declared by:
settings.restart.count
Maximum number of restart attempts when mode is up-to-count.
Once this limit is reached, the service is left stopped until you intervene or change the configuration.
Type: positive integer, meaning >0
Default:
5
Example:
3
Declared by:
settings.restart.mode
Selects the restart behavior.
never: do not restart failed services.up-to-count: restart up tocounttimes, then stop.always: always restart on failure.
Choose up-to-count if you want a service to get a few retries
during a transient failure, but still fail fast when the issue is
persistent. Choose always when continuous availability matters
more than surfacing the failure.
Type: one of “never”, “up-to-count”, “always”
Default:
"always"
Example:
"up-to-count"
Declared by:
settings.restart.time
Delay between restarts in milliseconds.
Increase this value for crash loops to give the system time to recover resources or for dependent services to come back.
Type: positive integer, meaning >0
Default:
1000
Example:
250
Declared by:
settings.startup
Startup behavior for the nimi process manager.
This section lets you run a one-time initialization command before any configured services are started. It is useful for bootstrapping state, preparing directories, or running a short setup task that should happen once per process manager start.
The command is executed once and then the normal service startup proceeds. If you do not need a startup hook, leave it unset.
Type: submodule
Default:
{ }
Example:
{
runOnStartup = /nix/store/abcd1234-my-init/bin/my-init;
}
Declared by:
settings.startup.runOnStartup
Path to a binary to run once at startup.
This should be a single executable in the Nix store, not a shell
snippet. Use lib.getExe to turn a package or derivation into a
runnable path.
The command runs before services start, so it is a good place to create files, check preconditions, or populate caches. If you need a long-running process, configure it as a service instead.
Set to null to disable.
Type: null or path in the Nix store
Default:
null
Example:
lib.getExe (
pkgs.writeShellApplication {
name = "example-startup-script";
text = ''
echo "hello world"
'';
}
)
Declared by: