Zoi Configuration

Zoi's behavior can be customized through one or more config.yaml files. This allows users and system administrators to configure everything from active package repositories to security policies. This document covers the structure of the configuration file, where to place it, and all the available options.

Configuration File Locations

Zoi uses a hierarchical configuration system, merging settings from up to three different locations. This allows for global system-wide settings to be overridden by user-specific or project-specific configurations.

The files are loaded and merged in the following order of precedence (lower numbers are overridden by higher numbers):

1. System: Global configuration for all users on the machine. This is the only location where a policy can be set to enforce settings.

   • Linux/macOS: /etc/zoi/config.yaml
   • Windows: C:\ProgramData\zoi\config.yaml

2. User: User-specific configuration. This is the most common file for users to edit.

   • Linux/macOS: ~/.zoi/pkgs/config.yaml
   • Windows: %USERPROFILE%\.zoi\pkgs\config.yaml

3. Project: Project-specific configuration, useful for team-based settings.

   • Path: ./.zoi/pkgs/config.yaml (relative to the current directory)

Settings from a higher-precedence file will override those from a lower-precedence file, unless a policy in the system configuration prevents it.

Configuration Schema

Here are all the fields available in config.yaml.

repos

A list of active repository tiers from the default registry that Zoi will search for packages.

• Type: list of string
• Example:

  repos:
    - core
    - main
    - community

default_registry

Configures the primary package database (registry) that Zoi syncs with.

• Type: object
• Fields:
  • handle: (string) A short, unique name for the registry. Zoi will determine this automatically on the first sync if left empty.
  • url: (string) The Git URL of the registry repository.
• Example:

  default_registry:
    handle: zoidberg
    url: https://github.com/Zillowe/Zoidberg.git

added_registries

A list of supplementary package registries to sync with, in addition to the default_registry.

• Type: list of object
• Fields: Same as default_registry.
• Example:

  added_registries:
    - handle: my-corp-registry
      url: https://git.mycorp.com/zoi-packages.git

git_repos

A list of raw Git repository URLs that contain Zoi packages. These are cloned into ~/.zoi/pkgs/git/ and can be used for personal or third-party package collections that are not full registries.

• Type: list of string
• Example:

  git_repos:
    - https://github.com/user/my-cool-pkgs.git

telemetry_enabled

Enables or disables Zoi's opt-in anonymous telemetry. See the Telemetry page for more details.

• Type: boolean
• Default: false
• Example: telemetry_enabled: true

rollback_enabled

If true, Zoi will keep the previous version of a package when upgrading, allowing for zoi rollback to function. If false, old versions are deleted immediately.

• Type: boolean
• Default: true
• Example: rollback_enabled: false

parallel_jobs

The number of parallel jobs to use during package installation. This can speed up the installation of multiple packages or packages with many dependencies.

• Type: integer
• Default: 3
• Example: parallel_jobs: 5

protect_db

If true, Zoi will make the package database directory (~/.zoi/pkgs/db) read-only after a zoi sync operation. Before syncing, it will automatically make it writable. This is a security feature to prevent accidental or malicious modification of package definitions.

• Type: boolean
• Default: false
• Example: protect_db: true

policy

A special object that can only be set in the system-wide configuration file (/etc/zoi/config.yaml). It allows administrators to lock down certain settings, preventing them from being overridden by user or project configs.

• Type: object
• See: The policy Object section below for details.

The policy Object

The policy object is designed for system administrators to enforce a consistent and secure Zoi environment across a machine. It can only be defined in the system-level config.yaml. All fields are boolean and default to false.

When a policy field is set to true, the corresponding configuration from the system config.yaml cannot be changed by a user or project config.yaml.

Policy Fields

• repos_unoverridable: If true, the repos list is locked.
• default_registry_unoverridable: If true, the default_registry cannot be changed.
• added_registries_unoverridable: If true, the added_registries list is locked.
• git_repos_unoverridable: If true, the git_repos list is locked.
• telemetry_enabled_unoverridable: If true, the telemetry_enabled setting is locked.
• rollback_enabled_unoverridable: If true, the rollback_enabled setting is locked.
• protect_db_unoverridable: If true, the protect_db setting is locked.
• allow_deny_lists_unoverridable: If true, the various allow/deny lists (allowed_packages, denied_licenses, etc.) are locked.
• signature_enforcement_unoverridable: If true, the signature_enforcement policy is locked.

Allow/Deny Lists

These lists allow administrators to control which packages, repositories, and licenses are permitted on a system. These are lists of strings.

• allowed_packages: If set, only packages from this list can be installed.
• denied_packages: Packages from this list cannot be installed.
• allowed_repos: If set, packages can only be installed from repositories in this list.
• denied_repos: Packages from repositories in this list cannot be installed.
• allowed_licenses: If set, only packages with licenses from this list (using valid SPDX identifiers) can be installed.
• denied_licenses: Packages with licenses from this list cannot be installed.

signature_enforcement

This object configures mandatory PGP signature verification for all pre-built packages.

• Type: object
• Fields:
  • enable: (boolean) If true, Zoi will only install pre-built packages (.pkg.tar.zst archives) that are signed by a trusted PGP key. It will not fall back to building from source.
  • trusted_keys: (list of string) A list of trusted PGP key names or fingerprints. These keys must already be present in the Zoi PGP keyring (see zoi pgp list).

Example Policy

This example (in /etc/zoi/config.yaml) enforces a strict security policy suitable for an enterprise environment.

# /etc/zoi/config.yaml

# Set the default registry to the corporate mirror
default_registry:
  handle: my-corp
  url: https://git.mycorp.com/zoi/zoidberg.git

# Activate only the 'core' and 'internal' repos
repos:
  - core
  - internal

# Define the policy to lock settings and enforce security constraints
policy:
  # Lock down the repository configuration
  default_registry_unoverridable: true
  repos_unoverridable: true
  added_registries_unoverridable: true

  # Enforce signature checking for all pre-built packages
  signature_enforcement_unoverridable: true
  signature_enforcement:
    enable: true
    trusted_keys:
      - MyCorp-Build-Key
      - 842293159C4B03357C8328D3A75793A3E674252E # Fingerprint for a specific admin

  # Lock down the allow/deny lists
  allow_deny_lists_unoverridable: true

  # Only allow OSI-approved licenses, but deny specific ones we don't want
  allowed_licenses:
    - MIT
    - Apache-2.0
    - BSD-3-Clause
  denied_licenses:
    - AGPL-3.0-only

  # Deny specific packages that are not approved for use
  denied_packages:
    - some-insecure-tool
    - another-unwanted-app