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.

A registry can publish its content either as a Git repository or as a single compressed snapshot called a .zrepo file, transferred incrementally through a zsync control file. See Snapshot Registries.

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

zoi install --repo clones the complete repository, evaluates its root zoi.lua, selects one exported package, installs it, and removes the temporary clone afterward. The complete tree remains available throughout dependency resolution and package builds, so adjacent IMPORT/INCLUDE files and local assets are preserved.

package({
    main = "./hello.pkg.lua",
    packages = {
        extra = "./packages/extra.pkg.lua"
    }
})

# Select the main export
zoi install --repo zillowe/hello

# Select a named export
zoi install --repo zillowe/hello:extra
zoi install --repo gl:zillowe/hello:extra
zoi install --repo cb:zillowe/hello:extra

# URL sources use a fragment selector
zoi install --repo 'https://github.com/zillowe/hello.git#extra'

package("./path.pkg.lua") remains shorthand for package({ main = "./path.pkg.lua" }). A source may also be a repository-relative folder. Zoi first tries <folder>/<folder-name>.pkg.lua; otherwise the folder must contain exactly one .pkg.lua file. Sources cannot escape the repository root.

If main is absent and only one named export exists, that export is selected. If several named exports exist without main, the command lists the available selectors.

Provider Prefixes:

• gh: or github: for GitHub (default if omitted).
• gl: or gitlab: for GitLab.
• cb: or codeberg: for Codeberg.

A repository can reuse another repository's exports through imports:

imports({
    shared = { repo = "zillowe/shared", rev = "main" }
})

package("shared:common")

Project imports are cloned below .zoi/imports/shared. Their requested revisions, exact resolved commits, and manifest hashes are stored in zoi.lock, allowing frozen installs to reproduce the same inputs.

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:

Snapshot Registries (.zrepo)Copy Anchor Link

Instead of cloning a Git repository, a registry can publish a single compressed snapshot of its entire contents. This is often much cheaper than a Git negotiation: a client downloads one immutable file and skips the clone, the packfile negotiation, and the object database entirely.

A .zrepo file holds the whole registry tree - repo.yaml, packages.json, and every .pkg.lua and .sec.yaml - as a sequence of independently compressed zstd frames, one per file, which decompress into an ordinary tar. The per-file framing is what lets a client transfer only the parts that changed; see Incremental updates. Because the tree is the same one a Git clone would produce, everything downstream (the metadata index, zoi search, zoi info, PURL resolution) works exactly as it does for a Git registry.

Declaring a snapshot registryCopy Anchor Link

Add a zrepo section to repo.yaml listing where the snapshots live. Like the git section, the type is main for the primary snapshot and mirror for fallbacks:

name: Zoidberg
description: Official Zoi packages repository
handle: zoidberg
advisory_prefix: ZSA
git:
  - type: official
    url: https://gitlab.com/zillowe/zillwen/zusty/zoidberg.git
zrepo:
  - type: main
    url: https://packages.example.com/zoidberg/main.zrepo
    control: https://packages.example.com/zoidberg/main.zrepo.zsync
    pgp: https://packages.example.com/zoidberg/main.zrepo.sig
    hash: https://packages.example.com/zoidberg/main.zrepo.sha256
  - type: mirror
    url: https://mirror.example.com/zoidberg/main.zrepo

Each ZrepoLink supports these fields:

If control is omitted, Zoi looks for the control file at <url>.zsync.

A zrepo registry needs no git section at all - the whole point of the snapshot is to replace the clone - so git and repos are both optional in a repo.yaml. A manifest declaring only name, description, and zrepo is valid.

Incremental updatesCopy Anchor Link

Snapshots are immutable, so a sync that finds an unchanged registry has nothing to do. When a new snapshot is published, the registry publishes a .zsync control file beside it, and Zoi transfers only the parts of the new snapshot it does not already hold.

The snapshot is stored as a sequence of independently compressed zstd frames, one per registry file. That framing is what makes this work: an entry that has not changed compresses to exactly the same bytes it did last time, so Zoi recognises it in its cached copy and skips it. A single compressed stream would resynchronise after the first edit and force a re-download of most of the file - measured at 53% of a snapshot for a three-line change, against 1.3% with per-entry framing.

The control file carries the snapshot's length, its SHA-1, and a table of per-block checksums, and is written by zync. The URL Zoi writes is a bare file name rather than an absolute address, because the publisher does not know where the snapshot will be hosted. Clients resolve it against the URL they fetched the control file from, so one control file serves a primary and every mirror unchanged, and Zoi further expands it with any mirrors you have configured locally.

Incremental transfers are strictly an optimization. The control field is entirely optional, and Zoi handles its absence in the way that suits the registry:

• control not declared: Zoi makes a single best-effort request for the conventional <url>.zsync and quietly downloads the full snapshot if there is nothing there. This is the normal state of affairs for a registry that has not adopted zsync, so it is not reported as a problem. If a publisher starts shipping control files later, they are picked up automatically.
• control declared but not served: the registry promised a control file and did not deliver, so Zoi warns and falls back to a full download.
• Control file present but unusable: a stale snapshot, a truncated download, a hash mismatch, or a server that cannot answer a range request. Zoi warns and falls back to a full download rather than installing anything it cannot fully verify.

In every case the snapshot is obtained in full, so a registry that never ships a control file syncs exactly as well as one that does - just without the bandwidth saving. A registry that stops publishing them is never left unsyncable, and no path through a failed update can leave a partially-applied registry behind.

The control file only decides how the bytes arrive. A completed transfer is verified against the published hash and pgp exactly as a full download is, so a registry's trust model does not change when it starts publishing one.

Zoi keeps the last snapshot it downloaded next to the registry index (as <handle>.zrepo) purely as the seed for the next transfer, and reuses it across syncs.

Adding a registry by URLCopy Anchor Link

A registry published as a repo.yaml document can be added directly by its URL:

zoi sync add https://packages.example.com/zoidberg/repo.yaml

Zoi fetches the repo.yaml, resolves the registry's real handle, name, description and advisory prefix, and records them. Only the content is deferred: the snapshot itself is downloaded on the next zoi sync. If the URL is not reachable, or turns out to be a plain Git URL, the registry is still recorded and the handle is resolved during the next sync.

A registry may also declare a git section alongside its zrepo section. When both are present, Zoi prefers the snapshot, because it is the cheaper transport. The Git repository remains a working fallback for clients that cannot fetch snapshots, and the control file covers the common case of a client that missed a release.

VerificationCopy Anchor Link

Snapshot registries use the same authorities mechanism as Git registries. When authorities are configured and the snapshot publishes a pgp signature, Zoi verifies the signature against those authorities before installing anything, and the registry's PGP keys are imported from repo.yaml first so they are available in the keyring. See Registry Verification.

A snapshot that fails verification is discarded, and a Git registry additionally rolls back to the last known-good signed commit.

Generating a snapshotCopy Anchor Link

Use zoi registry zrepo to build the snapshot from a registry checkout:

# Build main.zrepo, plus main.zrepo.zsync, from the registry in the current directory
zoi registry zrepo . -o main.zrepo

# Sign it with a key from your keyring, producing main.zrepo.sig
zoi registry zrepo . -o main.zrepo --sign your-key-id

The snapshot is reproducible: entries are sorted by name, timestamps are fixed to the epoch, and ownership is zeroed. Git plumbing and previous snapshots are excluded automatically. Reproducibility is load-bearing rather than cosmetic - because every unchanged file keeps a byte-identical compressed frame across publishes, that is precisely what lets a client skip fetching it.

The command writes three files: main.zrepo, the main.zrepo.zsync control file, and a .hash/.size sidecar pair (plus .sig when signing), matching the convention already used for .zpa artifacts.

Publishing an updateCopy Anchor Link

When the registry changes, publish a new snapshot. The control file is regenerated with it, so there is no separate patch to build:

# After updating packages and re-running 'zoi registry generate-metadata'
zoi registry zrepo . -o main.zrepo

The workflow a publisher follows is therefore:

• Publish main.zrepo at the url in the zrepo section.
• Publish main.zrepo.zsync (written by the same command) at the control URL, or at <url>.zsync if no control is declared.
• Serve main.zrepo.hash at the hash URL, if declared.
• Repeat on every release. A client that missed a release, or that holds no snapshot at all, falls back to a full download, so an unadopted control file costs bandwidth but never correctness.

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.