Repositories & Registries

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

Official package database

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

Managing the Package Database Registry

The package database is the core git repository that Zoi clones to ~/.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 the URL of the entire database registry itself using zoi sync.

This is useful if you want to use a mirror or a completely different package database.

Examples

# Show the current configured registries
zoi sync list

# Set the registry to the official GitHub mirror
zoi sync set github

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

Repository tiers

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 Repositories

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

Examples

# 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 ~/.zoi/pkgs/git/ 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 Installation

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.yaml file in its root. The package field in this file 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 repository

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.

  zoi install @community/htop

• From a specific sub-package:

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

  zoi install @core/linux:headers

• From a nested repository path:

  This is useful for platform-specific packages.

  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.

  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 ~/.zoi/pkgs/git/) and the package name.

  # 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.

  # 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 file

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:

PkgLink Placeholders

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

• {os}: The operating system (e.g. linux, macos, windows).
• {arch}: The CPU architecture (e.g. amd64, arm64).
• {version}: The version of the package.
• {repo}: The name of the sub-repository (e.g. core, main).

Example

name: Zoidberg
description: Official Zoi packages repository
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:
  - type: main
    url: https://zillowe.pages.dev/pkgs/{repo}/{os}/{arch}/{version}
    pgp: https://zillowe.pages.dev/pkgs/{repo}/{os}/{arch}/{version}.asc
    hash: https://zillowe.pages.dev/pkgs/{repo}/{os}/{arch}/{version}.txt
pgp:
  - name: zillowe-main
    key: https://zillowe.pages.dev/keys/zillowe-main.asc
repos:
  - name: core
    type: offical
    active: true
  - name: main
    type: offical
    active: true
  - name: extra
    type: offical
    active: true
  - name: community
    type: community
    active: false
  - name: archive
    type: archive
    active: false
  - name: test
    type: test
    active: false
  - name: zillowe
    type: offical
    active: false