Zoi Configuration

Zoi's behavior can be customized through two distinct configuration layers:

1. Hierarchical config.yaml: Standard YAML files for global system-wide policies, user preferences, and project-level settings.
2. Scriptable zoi.lua: The primary project configuration for defining dependencies, registries, and environment setup using Zoi's Lua API.

Configuration Hierarchy (config.yaml)

Zoi merges settings from up to three config.yaml 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 Policy: Project-specific overrides for system behavior.

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

Configuration Schema (config.yaml)

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.
  • advisory_prefix: (string, optional) The prefix for security advisory IDs from this registry (e.g. ZSA for Zoidberg Security Advisories).
  • authorities: (list of string, optional) PGP key identifiers trusted as authorities for this registry. Used to verify both registry git commit signatures and pre-built package archive signatures.

• Example:

  default_registry:
    handle: zoidberg
    url: https://github.com/zillowe/zoidberg.git
    advisory_prefix: ZSA
    authorities:
      - 842293159C4B03357C8328D3A75793A3E674252E

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
      advisory_prefix: MSA
      authorities:
        - my-corp-pgp-key

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

package_managers

Restricts the dependency managers Zoi may use when installing non-Zoi dependencies. If unset, Zoi detects available managers.

• Type: list of string

• Example:

  package_managers:
    - native
    - npm
    - cargo

native_package_manager

Overrides the detected native package manager used by native: dependencies.

• Type: string
• Example: native_package_manager: pacman

registry

Legacy shorthand for setting the default registry URL. If default_registry is not set, Zoi converts this into default_registry.url.

• Type: string
• Example: registry: https://github.com/zillowe/zoidberg.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

audit_log_enabled

Enables or disables persistent audit logging of all package operations (install, uninstall, upgrade). Logs are stored in ~/.zoi/audit.json and can be viewed with zoi history.

• Type: boolean
• Default: false
• Example: audit_log_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

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. Setting this to 0 will use all available CPU cores.

• Type: integer
• Default: 3
• Example: 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

max_resolution_depth

Configures the maximum recursion depth for package resolution when using the alt field in package definitions. This is a safety feature to prevent infinite loops caused by circular references.

• Type: integer
• Default: 7
• Value of 0: Disables the limit (infinite recursion allowed).
• Behavior when exceeded: Zoi will prompt the user to either continue or cancel the operation.
• Example: max_resolution_depth: 10

offline_mode

If true, Zoi will not attempt to connect to the network. It will rely entirely on local metadata and archive caches.

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

versions

A map of binary names to their preferred global versions. This is used by Zoi's intelligent shims to resolve which version of a tool to execute when multiple versions are installed and no project-specific version is defined.

• Type: object (map of string to string)

• Example:

  versions:
    node: "20.11.0"
    python: "3.12.1"

system_generations_limit

Defines the maximum number of ZoiOS system generations to keep in the store and bootloader. When a new generation is created, Zoi will automatically prune the oldest generations exceeding this limit.

• Type: integer
• Default: 4
• Value of 0: Infinite generations (no pruning).
• Note: The current active generation is never pruned.
• Example: system_generations_limit: 10

pkg_dirs

A list of additional directories to search for .zpa archives during installation.

• Type: list of string

• Example:

  pkg_dirs:
    - /mnt/usb/packages
    - /opt/zoi/archives

cache_mirrors

A list of base URLs used as fallbacks for archive downloads and archive metadata downloads (.hash, .size, .files). Zoi keeps the original upstream URL first, then tries each configured mirror using the requested filename.

• Type: list of string

• Example:

  cache_mirrors:
    - https://cache1.example.com/zoi
    - https://cache2.example.com/zoi

remote_policy

A remotely-hosted policy that Zoi fetches and caches at a regular interval. This allows centralized policy management without updating every machine's config.yaml.

• Type: object

• Must be set in: System-level config.yaml only.

• Fields:

  • url: (string) The URL to fetch the policy from.
  • signature_url: (string) The URL to fetch the detached PGP signature for the policy.
  • trusted_keys: (list of string) PGP key names or fingerprints trusted to sign the remote policy.

• Example:

  remote_policy:
    url: https://policy.example.com/zoi/policy.yaml
    signature_url: https://policy.example.com/zoi/policy.yaml.sig
    trusted_keys:
      - Corp-Security-Key

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.
• audit_log_enabled_unoverridable: If true, the audit_log_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.
• jobs_unoverridable: If true, the jobs setting is locked.
• advisory_enforcement_unoverridable: If true, advisory enforcement policy cannot be overridden by lower-precedence configs.
• system_generations_limit_unoverridable: If true, the system_generations_limit setting is locked.
• max_resolution_depth_unoverridable: If true, the max_resolution_depth setting is locked.
• offline_mode_unoverridable: If true, the offline_mode setting is locked.
• pkg_dirs_unoverridable: If true, the pkg_dirs list is locked.
• cache_mirrors_unoverridable: If true, the cache_mirrors list 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

By default, Zoi automatically verifies PGP signatures on pre-built packages when the registry defines authorities and the package provides a .sig file. The signature_enforcement policy configures a stricter mandatory mode for environments that require signatures on all packages.

• Type: object
• Fields:
  • enable: (boolean) If true, Zoi will only install pre-built packages (.zpa archives) that are signed by a trusted PGP key. It will fail on unsigned packages and 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