Zillowe Docs - 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 Functions

`system(table)`

Defines global system metadata and high-level configuration.

Field	Type	Description
`hostname`	`string`	The network hostname for the machine.
`timezone`	`string`	The system timezone (e.g. `"UTC"`, `"America/New_York"`).
`locale`	`string`	The primary system locale (e.g. `"en_US.UTF-8"`).
`kernel_params`	`string`	Appended to the kernel command line in the bootloader.
`desktop`	`string`	The desired desktop environment (e.g. `"kde"`, `"gnome"`, `"sway"`).

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

`bootloader(table)`

Configures the system bootloader.

Field	Type	Description
`type`	`string`	Required. One of `"systemd-boot"`, `"grub2"`, or `"limine"`.
`efi_dir`	`string`	Path to the EFI partition mount point (defaults to `"/boot/efi"`).
`timeout`	`number`	Boot menu timeout in seconds.

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

`packages(list)`

Defines the base set of packages installed in the system scope.

packages({
    "@core/linux",
    "@core/systemd",
    "@main/NetworkManager",
    "@main/git",
    "@main/neovim",
})

`users(table)`

Manages system user accounts.

Field	Type	Description
`password_hash`	`string`	A one-way hash generated by `zoi system secret hash`.
`groups`	`list`	Supplementary groups for the user.
`shell`	`string`	Path to the login shell (e.g. `"/usr/bin/zsh"`).
`home`	`string`	Custom path for the home directory.

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

`groups(table)`

Manages system groups.

Field	Type	Description
`gid`	`number`	Explicit Group ID (optional).

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

`services(table)`

Controls system-wide background services.

Field	Type	Description
`enable`	`boolean`	Whether to enable and start the service via `systemctl`.

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

`filesystems(list)`

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

Field	Type	Description
`device`	`string`	Device path or Label (e.g. `"/dev/sda1"`, `"LABEL=root"`).
`mount`	`string`	The target mount point (e.g. `"/"`, `"/home"`).
`type`	`string`	Filesystem type (e.g. `"btrfs"`, `"ext4"`, `"vfat"`).
`options`	`string`	Mount options (e.g. `"subvol=@root,compress=zstd:3"`).

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 Changes

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, and enable/disable services accordingly.

system.lua Reference