home.lua Reference

The ~/.config/zoi/home.lua file allows ZoiOS users to manage their personal environment, including dotfiles and user-scoped packages declaratively.

Core Functions

packages(table)

Defines the set of packages installed in the user scope (~/.zoi/pkgs/store). You can provide a simple list of names or a table for advanced pinning and option selection.

packages({
    -- Simple list
    "@community/bat",
    "cargo:ripgrep",

    -- Version pinning (exact)
    ["@community/neovim"] = { version = "0.9.5" },

    -- Version range pinning (SemVer)
    ["@community/eza"] = { version = "^0.18" },

    -- Channel pinning
    ["@community/ghostty"] = { version = "@nightly" },

    -- Advanced pinning and options
    ["@community/fzf"] = {
        version = "0.44.1",
        options = {"zoi:@main/fzf-shell-integration"},
        optionals = {"zoi:@main/fzf-tmux"}
    }
})

dotfiles(table)

Manages symbolic links for configuration files. Zoi will automatically create the symlink and its parent directories. Supports ~/ expansion for the source path.

dotfiles({
    [".zshrc"] = "~/code/dotfiles/zshrc",
    [".config/nvim"] = "~/code/dotfiles/nvim",
})

env(table)

Defines personal environment variables. Zoi writes these to ~/.zoi/env, which you can source in your shell profile.

env({
    EDITOR = "nvim",
    PAGER = "bat",
    -- Secrets are automatically decrypted if using ZOISEC strings
    OPENAI_API_KEY = "ZOISEC:v1:..."
})

Applying Changes

To apply your user configuration:

zoi home apply

Zoi will:

1. Resolve and install the listed packages to your user store.
2. Create symlinks for your dotfiles.
3. Generate ~/.zoi/env with your decrypted environment variables.

Shell Integration

To ensure your environment variables are always active, add this to your .bashrc or .zshrc:

# Source Zoi user environment
if [ -f "$HOME/.zoi/env" ]; then
    source "$HOME/.zoi/env"
fi