ZoiOS Management

ZoiOS (and its reference implementation, Parlex Linux) features a declarative system management engine powered by Zoi. These features allow you to manage the entire operating system state using a single Lua configuration file.

The zoi system Command

The zoi system suite is used to manage system-level generations and configuration.

zoi.system.apply [file]

Reads a system.lua file and applies its state to the machine. This involves:

1. Resolving all required packages.
2. Creating a new System Generation record.
3. Directly installing/updating packages in the system root within an atomic transaction.
4. Declarative State Enforcement: Automatically identifies and removes any packages currently installed in the system scope that are not explicitly listed in the configuration file.

# Apply the default system configuration
sudo zoi system apply

# Apply a specific configuration file
sudo zoi system apply ./my-server.lua

zoi system distro build --target <path> --config <file>

The primary command for bootstrapping new ZoiOS systems onto manually partitioned and formatted disks.

Safety Features:

• Pre-flight Validation: Automatically verifies that all base packages exist in your registry before touching the disk.
• Build Plan Summary: Shows a detailed table of configured filesystems and packages before proceeding.
• Dry-Run Mode: Use --dry-run to see exactly what commands will be executed without modifying your hardware.

# Preview the build plan
sudo zoi system distro build --target /mnt --config ./system.lua --dry-run

# Orchestrate the full build
sudo zoi system distro build --target /mnt --config ./system.lua

zoi system distro chroot <target>

Enter a ZoiOS sysroot (chroot) with automatic device mounting and sandbox protection. This is the recommended way to run commands like dracut or grub-install during the final stages of bootstrapping a ZoiOS installation, as it ensures all operations are safely contained within the target environment.

Options:

• --run <command>: Run a specific command inside the chroot and exit, rather than dropping into an interactive shell.

# Enter an interactive shell inside the ZoiOS root
sudo zoi system distro chroot /mnt/zoios

# Run a specific command inside the ZoiOS root
sudo zoi system distro chroot /mnt/zoios --run "grub-mkconfig -o /boot/grub/grub.cfg"

zoi system list

Lists all available system generations on the machine, including their creation date, the packages they contain, and their linked Zoi transaction IDs.

zoi system list

zoi system status

Shows the current system status, including the active generation ID and transaction state.

zoi system status

zoi system rollback <id>

Reverts the operating system to a previous generation by sequentially rolling back the Zoi package transactions that occurred after the target generation.

sudo zoi system rollback 41

zoi system secret

Manage sensitive information like passwords and API keys.

• zoi system secret hash <password>: Generates a one-way Argon2 hash of a password. Use this in your system.lua for user passwords.
• zoi system secret encrypt <value>: Encrypts a string so only Zoi on this specific machine can decrypt it. It returns a ZOISEC:v1:... string.

zoi system secret decrypt <ZOISEC>

Decrypts a ZOISEC string back to plaintext (useful if you forgot the value)

Declarative Configuration

ZoiOS uses two primary Lua files to manage its state:

• system.lua Reference: Manage system-wide packages, users, bootloaders, and filesystems.
• home.lua Reference: Manage your personal user environment, dotfiles, and user-scoped packages.

Bootstrapping a System

A functional ZoiOS system is defined by a collection package, typically @core/base. This package provides a foundational set of utilities (POSIX tools, C library, Shell) and allows you to choose your primary system components via interactive or declarative options.

The @core/base Profile

When installing or building a ZoiOS system, you can pre-select your core components in system.lua to avoid interactive prompts:

-- /etc/zoi/system.lua
packages({
    ["@core/base"] = {
        options = {
            "zoi:@core/systemd",         -- Choose your Init system
            "zoi:@core/linux-hardened", -- Choose your Kernel
            "zoi:@core/doas"            -- Choose your privilege escalator
        }
    }
})

Multi-Init and Escalation Support

ZoiOS is designed to be flexible. It supports multiple init systems and privilege escalation tools out of the box:

• Init Detection: Use SYSTEM.INIT in your .pkg.lua scripts to detect if the target system is running systemd or openrc.
• Privilege Escalation: Zoi automatically detects and uses either sudo or doas for Just-in-Time escalation. In your base package, these are interchangeable virtual providers.

Architectural Foundation

ZoiOS uses a Transaction-based architecture:

1. The Store: All packages reside in /var/lib/zoi/pkgs/store/, isolated by version and input hashes.
2. Shared Pool: Zoi packages use a "Shared Pool + Mapping" architecture. Files are stored in a central pool/ directory within the archive and mapped to their final destinations (/usr, /etc, etc.) at install time based on the scope.
3. Generations: A generation is a lightweight record (e.g. /var/lib/zoi/generations/42/) of the system state, linked to a specific Zoi package transaction.
4. Traditional Management: Unlike NixOS, ZoiOS installs files directly into the system root (usrroot). Rollbacks are performed by sequentially reverting package transactions, providing a traditional FHS experience with declarative safety.

Packaging Conventions

For developers building ZoiOS-native packages:

• Scope Awareness: Use ZOI.scope in your .pkg.lua to adjust behavior. When ZOI.scope == "system", files should generally be staged to ${usrroot}/usr/... or other absolute paths.
• Pooled ZPA: Zoi automatically builds "Pooled" archives that capture the package state for user, system, and project scopes simultaneously, ensuring zero duplication while supporting perfect scope-specific behavior.
• Transactional Safety: All changes to /usr, /etc, and /var are recorded in Zoi's transaction log, enabling atomic rollbacks of the entire system state.