Repositories & Registries

This page explains Zoi's official repositories and mirrors, and how package repositories are organized by tier.

Official package databaseCopy Anchor Link

• Packages database (Zoidberg)
  • Primary: GitLab
  • Mirrors: GitHub, Codeberg

Managing the Package Database RegistryCopy Anchor Link

The package database is the core git repository that Zoi clones to its user data directory under zoi/pkgs/db. This repository contains all the package definitions organized into tiers. While you can manage which repositories inside the database are active using zoi repo, you can also change which package database registry Zoi uses via zoi sync.

Official and supported registries are shipped as built-in definitions embedded in the Zoi binary (see Specifications). You can reference them by their handle instead of a full URL, and Zoi derives the git URL and metadata automatically.

ExamplesCopy Anchor Link

# Sync the system-wide package database (/var/lib/zoi/pkgs/db)
sudo zoi sync --scope system

# Sync registries into a target sysroot during bootstrapping
sudo zoi sync --root /mnt --scope system

Automatic Scope DetectionCopy Anchor Link

Zoi is intelligent about where it stores metadata:

• Running as Root? Zoi defaults to --scope system.
• Using --root? Zoi defaults to --scope system within the target.
• Normal User? Zoi defaults to --scope user in the user data directory under zoi/pkgs/db.

# Show the current configured registries, including unadded built-ins
zoi sync list

# Set the default registry to the official Zoidberg registry (by handle)
zoi sync set zoidberg

# Set the default registry to the built-in set registry
zoi sync set default

# Set the default registry to a custom URL
zoi sync set https://my-custom-registry.com/zoidberg.git

# Add an additional registry by handle (third-party registries warn first)
zoi sync add my-company

# Force a full re-sync from scratch (preserves installed packages)
zoi sync --force

Registry MaintenanceCopy Anchor Link

For instructions on how to create and maintain your own registry, see the Registry Maintenance guide.

Repository tiersCopy Anchor Link

Zoi organizes packages into tiers. Use these to decide where a package belongs and to assess stability, example tiers (from Zoidberg).

Note: Packages from community, test, and archive may carry higher risk. Zoi prints warnings where appropriate.

Managing Active RepositoriesCopy Anchor Link

The zoi repo command manages which repositories from the package database are active. Active repositories are searched during package operations like install and search.

ExamplesCopy Anchor Link

# Add a repository interactively
zoi repo add

# Add official repositories by name
zoi repo add core
zoi repo add main
zoi repo add community

# Add by git URL (cloned under the user data directory and used via #git@<repo>/<pkg>)
zoi repo add https://github.com/YourOrg/my-zoi-repo.git

# Remove and list
zoi repo rm community
zoi repo list
zoi repo list all
zoi repo git ls
zoi repo git rm my-zoi-repo

Direct Git Repository InstallationCopy Anchor Link

In addition to adding a git repository to your local configuration with zoi repo add, you can install a package directly from a remote git repository using the --repo flag with zoi install.

# Install from a GitHub repository
zoi install --repo zillowe/hello

# Install from a GitLab repository
zoi install --repo gl:zillowe/hello

# Install from a Codeberg repository
zoi install --repo cb:zillowe/hello

This works if the target repository has a zoi.lua file in its root declaring package("..."). The declaration can specify a package name (e.g. hello), a path to a .pkg.lua file within the repository, or a URL to a .pkg.lua file. This provides a quick way to install packages from git repositories without permanently adding them to your configuration.

Provider Prefixes:

• gh: or github: for GitHub (this is the default if no prefix is given).
• gl: or gitlab: for GitLab.
• cb: or codeberg: for Codeberg.

Installing from a specific repositoryCopy Anchor Link

You can specify which repository or registry to install a package from using special prefixes.

• From a top-level repository in the default registry:

  This installs htop from the community repository.

  Copy Text

  zoi install @community/htop

• From a specific sub-package:

  This installs the headers sub-package from the linux package in the core repository.

  Copy Text

  zoi install @core/linux:headers

• From a nested repository path:

  This is useful for platform-specific packages.

  Copy Text

  zoi install @core/linux/amd64/nvidia-driver

• From a specific registry:

  If you have multiple registries configured (see zoi sync list), you can target one using its handle. This installs my-package from the my-repo repository within the my-registry registry.

  Copy Text

  zoi install #my-registry@my-repo/my-package

• From a custom git repository:

  Use the #git@ prefix, followed by the repository name (the directory name in the user data directory's zoi/pkgs/git/) and the package name.

  Copy Text

  # Install from a nested directory within the git repo
  zoi install #git@my-zoi-repo/path/to/package

• From a remote git repository on the fly:

  You can install a package directly from a remote git repository that acts as a Zoi registry, without adding it first. This is useful for testing or one-off installations. The repository must contain a repo.yaml file.

  The syntax is #git:<host>/<user>/<repo>@<repo_in_registry>/<package>.

  Supported hosts are github.com, gitlab.com, and codeberg.org.

  Copy Text

  # Install 'my-package' from the 'community' repo inside a registry hosted on GitHub
  zoi install '#git:github.com/some-user/my-zoi-registry@community/my-package'

For creating packages, see Creating Packages.

For publishing packages, see Publishing Packages.

The repo.yaml fileCopy Anchor Link

A Zoi package registry is defined by a repo.yaml file at its root. This file contains metadata about the repository, such as its name, description, and the URLs for its git repository and pre-built packages. When you run zoi sync, Zoi also automatically imports any PGP keys listed in the pgp section.

Here are the fields available in repo.yaml:

Registry VerificationCopy Anchor Link

For security-conscious environments, Zoi supports verifying the integrity of an entire registry via Git commit signatures. By defining authorities in your local configuration, you can ensure that Zoi only syncs with a registry if its latest state has been signed by a trusted maintainer.

Configuring AuthoritiesCopy Anchor Link

You can add authorities to your default_registry or any entries in added_registries in your config.yaml:

added_registries:
  - handle: my-team
    url: https://git.company.com/team/zoidberg.git
    authorities:
      - "842293159C4B03357C8328D3A75793A3E674252E"

If a registry has authorities configured, zoi sync will:

1. Fetch the latest commit from the Git remote.
2. Check for a PGP signature on that commit.
3. Verify that the signature was made by one of the listed authorities.
4. Abort the sync if verification fails.

This establishes a "Chain of Trust" where the registry maintainer signs the entire repository state, guaranteeing that every .pkg.lua file and the repo.yaml itself have not been tampered with.

PkgLink PlaceholdersCopy Anchor Link

The url, pgp, hash, size, and files fields within a PkgLink object can contain the following placeholders, which Zoi will replace at runtime:

• {name}: The name of the package.
• {version}: The version of the package.
• {id}: A flattened unique identifier (repo path + name with slashes replaced by dots, e.g. core.editors.vim). Recommended for GitLab Generic Package Registry.
• {os}: The operating system (e.g. linux, macos, windows).
• {arch}: The CPU architecture (e.g. amd64, arm64).
• {platform}: The full platform string (e.g. linux-amd64).
• {repo}: The name of the sub-repository (e.g. core, main).

DeltaLink PlaceholdersCopy Anchor Link

The url, pgp, hash, and size fields within a DeltaLink object can contain the following placeholders, which Zoi will replace at runtime:

• {name}: The name of the package.
• {version}: The target version of the package (the version being upgraded to).
• {id}: A flattened unique identifier (repo path + name with slashes replaced by dots, e.g. core.editors.vim).
• {os}: The operating system (e.g. linux, macos, windows).
• {arch}: The CPU architecture (e.g. amd64, arm64).
• {platform}: The full platform string (e.g. linux-amd64).
• {repo}: The name of the sub-repository (e.g. core, main).

Zoi uses a smart URL construction strategy:

• If your url template ends with .zpa, Zoi uses it exactly as generated. This gives you full control over the file path.
• If it does not end with .zpa, Zoi assumes the URL points to a directory and automatically appends the standard filename format: {name}-{version}-{platform}.zpa.

ExampleCopy Anchor Link

name: Zoidberg
description: Official Zoi packages repository
handle: zoidberg
advisory_prefix: ZSA
git:
  - type: main
    url: https://gitlab.com/zillowe/zillwen/zusty/zoidberg.git
  - type: mirror
    url: https://github.com/zillowe/zoidberg.git
  - type: mirror
    url: https://codeberg.org/zillowe/zoidberg.git
pkg:
  # Pre-built packages (GitLab Generic Package Registry)
  - type: main
    url: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa
    pgp: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa.sig
    hash: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa.hash
    size: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa.size
    files: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zpa.files
  # Source bundles
  - type: source-main
    url: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}.zsa
    hash: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}.zsa.hash
    pgp: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}.zsa.sig
    size: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}.zsa.size
    files: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}.zsa.files
delta:
  # Delta patches for bandwidth-efficient upgrades
  - type: main
    url: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zdelta
    pgp: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zdelta.sig
    hash: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zdelta.hash
    size: https://gitlab.com/api/v4/projects/71125308/packages/generic/{id}/{version}/{name}-{version}-{platform}.zdelta.size
pgp:
  - name: zillowe-main
    key: https://zillowe.pages.dev/keys/zillowe-main.asc
repos:
  - name: core
    type: official
    active: true
  - name: main
    type: official
    active: true
  - name: extra
    type: official
    active: false
  - name: community
    type: community
    active: false
  - name: archive
    type: archive
    active: false
  - name: test
    type: test
    active: false

Delta PatchesCopy Anchor Link

Zoi supports bandwidth-efficient upgrades using .zdelta patches (bsdiff-based deltas applied to the content-addressed pool). When a previous version of a package is cached and a delta is available from the registry, Zoi will download the delta patch, verify its hash and signature, apply it to the cached archive, and install the rebuilt package.

Delta patches are configured explicitly in the delta section of repo.yaml. Each DeltaLink supports the same mirror types as PkgLink (main, mirror).

Required fields for secure delta upgrades:

• url: The delta patch URL template (must contain {version} placeholder for the target version).
• hash: URL to the delta patch's SHA-256 hash file (mandatory for integrity).
• pgp: URL to the delta patch's detached PGP signature (recommended for authenticity).
• size: URL to the delta patch's size file (for progress reporting).

Example delta configuration:

delta:
  - type: main
    url: https://example.com/deltas/{id}/{version}/{name}-{version}-{platform}.zdelta
    pgp: https://example.com/deltas/{id}/{version}/{name}-{version}-{platform}.zdelta.sig
    hash: https://example.com/deltas/{id}/{version}/{name}-{version}-{platform}.zdelta.hash
    size: https://example.com/deltas/{id}/{version}/{name}-{version}-{platform}.zdelta.size
  - type: mirror
    url: https://mirror.example.com/deltas/{id}/{version}/{name}-{version}-{platform}.zdelta
    hash: https://mirror.example.com/deltas/{id}/{version}/{name}-{version}-{platform}.zdelta.hash

When upgrading, Zoi looks up the delta URL using the target version (the version being upgraded to). The delta patch is verified against its hash and signature before application. If no delta is configured, unavailable, or fails verification, Zoi silently falls back to downloading the full archive.

When the cached version is more than one release behind the target, Zoi applies deltas sequentially: each intermediate delta is downloaded, verified, and applied on top of the previously rebuilt archive until the target version is reached (for example cached 149 with target 151 applies 149 -> 150, then 150 -> 151). Intermediate versions are read from the package database. The number of steps is limited by the max_delta_steps user config (default 3); anything beyond that falls back to a full download.

Creating delta patches:

Use zoi package delta to generate a .zdelta between two .zpa archives:

# Generate delta with automatic naming
zoi package delta old-package-1.0.0-linux-amd64.zpa new-package-1.1.0-linux-amd64.zpa

# Generate signed delta for distribution
zoi package delta --sign <KEY> old-package-1.0.0-linux-amd64.zpa new-package-1.1.0-linux-amd64.zpa

This creates the .zdelta file plus sidecar files: .zdelta.hash, .zdelta.size, and .zdelta.sig (if --sign is used). Distribute these alongside your package archives in the registry.

Registry Metadata FilesCopy Anchor Link

When Zoi downloads a pre-built package, it optionally looks for accompanying .hash and .size files to verify integrity and report installation progress.

The .hash FileCopy Anchor Link

This file contains the cryptographic hash of the .zpa archive.

• Format: Zoi supports standard hash file formats (like those generated by sha512sum).
• Parsing: Zoi will search the file for a 128-character hex string (for SHA-512) that is associated with the archive's filename. If the file contains only a single hash string, Zoi will use that.
• Supported Algorithms: SHA-512 (recommended) and SHA-256.
• Caching: During zoi sync, Zoi downloads .hash files alongside .size and caches them in the local database. This means archive integrity verification does not require a network request during installation.

The .size FileCopy Anchor Link

This file provides the download and expected installation sizes to Zoi before the archive is even downloaded. This allows for accurate disk space checks and progress reporting. During zoi sync, Zoi automatically downloads .size files when available and caches them locally, so size display does not require a network request.

• Format: A text file containing key-value pairs or a single number.
• Fields:
  • down: <bytes>: The size of the compressed .zpa archive.
  • install: <bytes>: The total size the package will occupy on disk after extraction.
• Fallback: If the file contains only a single numeric value, Zoi treats it as the down (download) size.

Example .size file:

down: 11214
install: 124114

The .files FileCopy Anchor Link

This file contains a plain-text list of all files contained within the package archive, including their destination paths (relative to the staging structure, e.g. data/usrroot/usr/bin/hello).

• Purpose: Allows Zoi to perform "Enhanced Conflict Detection" by checking for file overwrites on the local system before downloading the actual package binary.
• Upgrade Safety: Zoi automatically ignores conflicts for files that are already owned by the same package during an upgrade.
• Format: One file path per line.
• Caching: During zoi sync, Zoi downloads .files metadata and indexes them in a dedicated package_files SQLite table with FTS5 full-text search support. This enables instant file search via zoi search --files without additional network requests.