Service Options Reference

Usage

nixda.zones.<name>.services.<name>.

_nixda.versionDeclaration

Type: null or (submodule)

WHERE a blueprint’s mk constructor populates this attribute, the versions module reads the triple at zone materialization time to emit drift diagnostics. Default is null so pre-migration services and hand-written service declarations evaluate cleanly without change.

_nixda.versionDeclaration.composed

Type: attribute set of string

Per-version-key fully-composed image string the blueprint would materialize from effective. Used by the drift module to detect silent image-string overrides: a downstream lib.recursiveUpdate that rewrites runtime.oci.image without flowing through mk will leave composed recording the expected string while the materialized image string differs.

Single-image blueprints record one entry: composed = { main = ”:${effective.main}”; } Composite-pod blueprints record one entry per pod-member key with the appropriate per-member repository prefix.

Default is \{\} so pre-migration services evaluate cleanly; the drift module’s anti-pattern check skips services whose composed map is empty.

_nixda.versionDeclaration.declared

Type: null or (attribute set of string)

Consumer-supplied versions attrset captured at the blueprint mk call site. null means the consumer inherited blueprint defaults; a non-null value means the consumer explicitly pinned one or more keys.

_nixda.versionDeclaration.effective

Type: attribute set of string

The version map that was actually composed into the runtime image string (i.e. declared merged over recommended). Populated by the blueprint constructor; not set by consumers.

_nixda.versionDeclaration.recommended

Type: attribute set of string

The blueprint’s current default version map at the time of mk invocation. Populated by the blueprint constructor; not set by consumers.

dependsOn

Type: list of string

Default: [ ]

Service names (within the same zone) that must start before this service.

id

Type: integer between 1 and 254 (both inclusive)

Unique ID for the service. Used for IP allocation (10.100.{zone_id}.{id}).

idleTimeout

Type: null or signed integer

Default: 43200

Seconds of inactivity before the service is stopped (null to disable).

ports

Type: list of 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: [ ]

List of TCP ports the service listens on internally.

prefixMapping

Type: attribute set of 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Maps URL path prefixes to specific internal ports. Example: { “/api” = 8080; }

restart.delaySec

Type: signed integer

Default: 10

Initial delay between restarts in seconds.

restart.limitBurst

Type: signed integer

Default: 10

Maximum restart attempts within limitIntervalSec.

restart.limitIntervalSec

Type: signed integer

Default: 1800

Time window for restart limit in seconds.

restart.maxDelaySec

Type: signed integer

Default: 300

Maximum delay between restarts in seconds (exponential backoff ceiling).

restart.steps

Type: signed integer

Default: 5

Number of exponential backoff steps from delaySec to maxDelaySec.

runtime.native

Type: null or (submodule)

Configuration for a Native NixOS Container.

runtime.native.capabilities

Type: list of string

Default: [ ]

Additional Linux capabilities for the systemd-nspawn container. Example: [ “CAP_SYS_ADMIN” ] for Docker-in-nspawn.

runtime.native.configuration

Type: module

NixOS configuration for the container.

runtime.native.credentialEnvFiles

Type: attribute set of (submodule)

Generate EnvironmentFile-compatible files from raw credentials. Each entry creates /run/credentials-env/ containing VARIABLE=. Use when a NixOS module expects EnvironmentFile format but credentials are raw values.

runtime.native.credentialEnvFiles.<name>.credential

Type: string

Name of the credential in /run/credentials/@system/.

runtime.native.credentialEnvFiles.<name>.variable

Type: string

Environment variable name (e.g. TOKEN).

runtime.native.credentials

Type: attribute set of path

Credentials passed into the container via systemd-nspawn —load-credential. Maps credential name to host path. Symlinks are followed. Available at /run/credentials/@system/ inside the container.

runtime.native.extraNspawnFlags

Type: list of string

Default: [ ]

Additional flags passed directly to systemd-nspawn. Example: [ “—system-call-filter=bpf” ] to allow BPF syscalls.

runtime.native.sopsTemplates

Type: attribute set of (submodule)

Files rendered by sops-nix at activation and passed into the container as systemd credentials. Each attribute name is both the template name and the credential name, so a template declared here is readable inside the container at /run/credentials/@system/.

Use this instead of credentials when a file must mix secret and non-secret content — a config file holding one encrypted field, for example. The rendered file exists only at runtime and never enters the Nix store.

runtime.native.sopsTemplates.<name>.content

Type: function that evaluates to a(n) string

Function from an attrset of placeholders to the file’s text. The attrset maps each name in secrets to its sops placeholder, so a template never sees a secret value at evaluation time.

The placeholder is looked up through config.sops.placeholder, never reconstructed: sops-nix marks that option visible = false, so the sentinel’s format is an internal contract between eval-time interpolation and the activation-time renderer.

runtime.native.sopsTemplates.<name>.secrets

Type: list of string

Names of sops.secrets entries this template interpolates. Each becomes a key of the attrset passed to content.

runtime.native.volumes

Type: list of string

Default: [ ]

Bind mounts for the container.

runtime.oci

Type: null or (submodule)

Configuration for an OCI (Podman) Container.

runtime.oci.environment

Type: attribute set of string

Environment variables for the container.

runtime.oci.image

Type: string

The OCI image to run (e.g. ‘nginx:latest’).

runtime.oci.pod

Type: attribute set of (submodule)

Additional containers grouped into a Podman pod with the entrypoint. All pod members share a network namespace (communicate via localhost). When non-empty, oci-service.nix creates a Podman pod instead of a standalone container. The entrypoint (image/environment/volumes above) is the pod’s main container.

runtime.oci.pod.<name>.cmd

Type: list of string

Default: [ ]

Override the container command.

runtime.oci.pod.<name>.environment

Type: attribute set of string

Environment variables for this pod member.

runtime.oci.pod.<name>.image

Type: string

The OCI image to run.

runtime.oci.pod.<name>.volumes

Type: list of string

Default: [ ]

Volume mounts for this pod member.

runtime.oci.volumes

Type: list of string

Default: [ ]

Volume mounts for the container.

runtime.system

Type: null or (submodule)

Configuration for a direct host system service.

runtime.vm

Type: null or (submodule)

Configuration for a MicroVM.

runtime.vm.configuration

Type: module

NixOS configuration for the MicroVM.

runtime.vm.cores

Type: signed integer

Default: 1

CPU cores.

runtime.vm.ram

Type: signed integer

Default: 1024

RAM in MB.

runtime.vm.volumes

Type: list of string

Default: [ ]

Shared directories/volumes.

socketActivation

Type: boolean

Default: false

Enable socket activation with idle timeout proxy chain. When false, Caddy proxies directly to the service IP.

stripPrefix

Type: boolean

Default: true

Whether to strip the service name prefix from the request path before forwarding.