Declarative System Configuration

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.