Zillowe FoundationZillowe Documentation
ZDSZoi

Declarative System Configuration

Manage your Arch Linux system state declaratively with zoi.lua.

Zoi provides a powerful way to manage your Arch Linux system state declaratively using a zoi.lua file. This feature is inspired by tools like NixOS and Home Manager, allowing you to define your desired system state in a single file and apply it with one command.

Important

This feature is currently only supported on Arch Linux systems and requires administrator privileges (sudo).

The zoi.lua File

The system configuration is defined in a Lua script located at a system-level path:

  • Path: /etc/zoi/zoi.lua

This file uses the system_config{...} function to declare the desired state of your system.

Full Example zoi.lua

system_config({
  -- You can split your config into multiple files
  imports = {
    "./hardware.lua",
    "./network.lua"
  },

  -- 1. Basic System Settings
  hostname = "my-arch-workstation",
  locale = "en_US",
  timezone = "Europe/London",

  -- 2. Bootloader & Hardware
  boot = {
    kernel_params = {"quiet", "splash", "nvidia-drm.modeset=1"}
  },
  hardware = {
    microcode = "amd", -- "amd" or "intel"
    drivers = {"nvidia"} -- "nvidia", "amdgpu"
  },

  -- 3. Networking
  network = {
    manager = "NetworkManager",
    firewall = {
      enable = true,
      allowed_tcp_ports = {22, 80, 443},
      allowed_udp_ports = {53}
    }
  },

  -- 4. User Environment
  shell = "zsh", -- Changes your user shell to /bin/zsh
  desktop = "kde", -- Options: kde, gnome, xfce, sway, hyprland

  -- 5. Users and Groups
  groups = {
    ["docker"] = {}
  },
  users = {
    ["alice"] = {
      groups = {"wheel", "docker"},
      shell = "/bin/zsh",
      -- Password encrypted via `zoi system encrypt`
      password = "ab12...:cd34..."
    }
  },

  -- 6. Package Management
  -- Can include zoi packages or native (pacman) packages
  packages = {
    "native:git",
    "native:vim",
    "zoi:htop",
    "zoi:eza",
    "zoi:bat",
    "zoi:nodejs@20"
  },

  -- 7. Programs (High-level Abstractions)
  programs = {
    git = {
      userName = "Alice Zoi",
      userEmail = "[email protected]"
    }
  },

  -- 8. Zoi Extensions
  extensions = {
    "audit-plugin"
  },

  -- 9. File Management (Dotfiles / Configs)
  files = {
    ["~/.zshrc"] = {
      content = "export PROMPT='%n@%m %~ %# '",
      executable = false
    },
    ["/etc/motd"] = {
      content = "Welcome to Zoi-managed Arch Linux!",
      owner = "root",
      mode = 420 -- 0644 octal
    },
    ["~/.config/nvim/init.lua"] = {
      source = "https://raw.githubusercontent.com/user/dots/main/init.lua"
    }
  },

  -- 10. Environment Variables & Aliases
  -- These are written to /etc/profile.d/zoi_declarative.sh
  env = {
    EDITOR = "nvim",
    PATH = "$HOME/.local/bin:$PATH"
  },
  aliases = {
    ls = "eza",
    cat = "bat"
  },

  -- 11. System Services
  services = {
    "bluetooth",
    "docker"
  }
})

Secure Passwords (zoi system encrypt)

To avoid storing plaintext passwords in your /etc/zoi/zoi.lua file, Zoi provides a built-in encryption mechanism tied to your specific machine.

  1. Generate an encrypted string using: 
    sudo zoi system encrypt "my_secure_password"
  2. Copy the resulting output string into the password field of your user configuration.
  3. During zoi system apply, Zoi decrypts the string using a securely stored /etc/zoi/machine_key and sets the user's password.

Usage

Once you have defined your desired state in /etc/zoi/zoi.lua, you can apply it using the following command:

sudo zoi system apply

What zoi system apply does:

  1. Validates Platform: Ensures you are running on Arch Linux.
  2. Hostname & Localization: Updates /etc/hostname, /etc/locale.gen, and /etc/localtime.
  3. Desktop Environment: Automatically installs the necessary meta-packages for your chosen DE.
  4. Shell: Changes your default shell via chsh.
  5. Synchronizes Packages: Installs missing Zoi and native packages.
  6. Synchronizes Extensions: Adds missing Zoi extensions.
  7. File Management: Creates directories and writes files (supporting raw content, local sources, or remote URLs).
  8. Env & Aliases: Generates a system-wide profile script for your environment variables and aliases.
  9. Synchronizes Services: Ensures systemd services are enabled and started.

Key Benefits

  • Nix-like Reproducibility: Recreate your entire workstation environment from a single Lua file.
  • Atomic Operations: Package installations and extension additions are managed by Zoi's transactional engine.
  • Dynamic Logic: Since it's Lua, you can use conditional logic (e.g. install different packages based on the CPU architecture).
  • Native & Sandboxed Mix: Seamlessly combine native system tools with Zoi's isolated package store.
Zillowe Foundation Logo

Zillowe Foundation

A software organization

2026 © All Rights Reserved.

  • All the content is available under CC BY-SA 4.0, expect where otherwise stated.

Last updated on

Project Configuration

Define project commands and environments with zoi.yaml.

Creating Packages

A complete guide on how to create and build Zoi packages.

On this page

The zoi.lua File
Full Example zoi.lua
Secure Passwords (zoi system encrypt)
Usage
What zoi system apply does:
Key Benefits