system.lua Reference

The /etc/zoi/system.lua file is the primary configuration file for ZoiOS. It allows administrators to define the entire state of the operating system, from kernel parameters to user accounts as code.

Core FunctionsCopy Anchor Link

system(table)Copy Anchor Link

Defines global system metadata and high-level configuration.

system({
    hostname = "parlex-station",
    timezone = "America/Los_Angeles",
    locale = "en_US.UTF-8",
    kernel_params = "quiet loglevel=3 mitigations=off",
})

bootloader(table)Copy Anchor Link

Configures the system bootloader.

bootloader({
    type = "systemd-boot",
    timeout = 5,
})

Leaving type unset lets Zoi detect the bootloader from the filesystem, probing systemd-boot first, then GRUB 2, then Limine.

efi_dir is only consulted for limine, whose entries use ESP-relative paths. systemd-boot writes to /boot/loader/entries and probes the ESP mount point (/boot, /boot/efi, /efi) itself, because the entries have to land on the filesystem the firmware actually reads.

One boot entry is written per kernel, including kernels preserved as fallbacks by kernel_retention, so several remain selectable after an update.

packages(table)Copy Anchor Link

Defines the base set of packages installed in the system scope. You can provide a simple list of names or a table for advanced pinning and option selection.

packages({
    -- Simple list
    "@core/linux",
    "@core/systemd",

    -- Pinning to a specific version or range
    ["@main/neovim"] = { version = "^0.10" },

    -- Pinning to a channel
    ["@core/zoi"] = { version = "@stable" },

    -- Advanced pinning and options
    ["@core/base"] = {
        options = {
            "zoi:@core/systemd",
            "zoi:@core/linux",
            "zoi:@core/sudo"
        }
    }
})

users(table)Copy Anchor Link

Manages system user accounts.

users({
    zaid = {
        password_hash = "$argon2id$v=19$m=65536,t=3,p=4$...",
        groups = { "wheel", "video", "docker" },
        shell = "/usr/bin/bash",
    }
})

Accounts are written directly to /etc/passwd, /etc/shadow, /etc/group and /etc/gshadow. The behaviour worth knowing:

• Idempotent. Re-applying an unchanged system.lua performs no writes, so zoi system apply is safe to run on a schedule.
• Deterministic. Users are processed in sorted order, so two machines applying the same configuration end up with identical UIDs.
• Existing UIDs are never reassigned. Changing a UID under a populated home directory would orphan every file in it.
• Home directories are created from /etc/skel with mode 0700.
• An account with no password_hash is locked, not passwordless. It cannot be logged into with a password, but root su and SSH key login still work.
• ZOISEC: values are decrypted automatically, so an encrypted secret works directly as password_hash.
• A missing group reference warns rather than failing, so one typo does not abort an apply.

groups(table)Copy Anchor Link

Manages system groups.

groups({
    docker = { gid = 999 }
})

Groups are reconciled before users, because a user's supplementary memberships have to resolve to real GIDs.

Accounts the base packages already ship (root, nobody, and so on) are left alone. system.lua is the source of truth for whether a group exists, not for every attribute of it, because the packages that own those groups have deliberate GIDs and memberships that a declarative file would otherwise fight on every apply.

services(table)Copy Anchor Link

Controls system-wide background services.

services({
    NetworkManager = { enable = true },
    sshd = { enable = true },
    docker = { enable = true },
})

filesystems(list)Copy Anchor Link

Defines the disk layout and mount points for /etc/fstab.

filesystems({
    {
        device = "LABEL=zoios_root",
        mount = "/",
        type = "btrfs",
        options = "subvol=@root,compress=zstd:3,ssd",
    },
    {
        device = "LABEL=zoios_root",
        mount = "/home",
        type = "btrfs",
        options = "subvol=@home,compress=zstd:3",
    }
})

Applying ChangesCopy Anchor Link

To apply your changes to the live system:

sudo zoi system apply

Zoi will resolve the packages, install them to the store, create a new System Generation, update the FHS view, reconcile the declared users and groups, regenerate /etc/fstab, enable or disable services, run the kernel pipeline, and write bootloader entries.

The apply is idempotent: running it twice with no change in between performs no writes, which is what makes it safe to schedule.