DOCSEARCHbyAlgolia
Submit Docs

nanobrew

repository·main·Indexed 22 days ago

https://github.com/justrach/nanobrew

A fast package manager for macOS and Linux written in Zig. It serves as a high-performance alternative to Homebrew, featuring native install pipelines for top formulae/casks, parallel downloads, and a single static binary without a Ruby runtime. It supports Homebrew bottles, macOS Casks, Linux .deb packages, and third-party taps, while providing features like version pinning, shimmed installs for private dependencies, and a relocated store cache for faster reinstalls.

Tokens
22.5K
Snippets
87
Records
119
Agent score
76%

What's inside nanobrew

  1. How extended keg linking works in nanobrew

    main

    Nanobrew uses a linking process to make package contents accessible within the global prefix. Previously, only bin/ and sbin/ were symlinked. The extended linking design ensures that libraries, headers, and shared data are also available by mirroring specific keg subdirectories into the prefix.

    Linked Directories:

    • bin/ and sbin/ $\rightarrow$ prefix/bin/ (Executables)
    • lib/ $\rightarrow$ prefix/lib/ (Shared libraries, .a archives, pkgconfig)
    • include/ $\rightarrow$ prefix/include/ (C/C++ headers)
    • share/ $\rightarrow$ prefix/share/ (Man pages, completions, locale data)

    Conflict Handling Logic: When a symlink target already exists:

    1. If the existing symlink points to the same keg (e.g., during a reinstall or upgrade), the existing link is overwritten.
    2. If the existing symlink points to a different keg, nanobrew will skip the link and print a warning: nb: warning: <path> already linked by <other_package>, skipping.

  2. Criteria for installing package-manager CLIs

    main

    Nanobrew follows a strict policy regarding CLIs distributed via package managers (like npm or pip).

    Eligible (Allowed)

    To be included in the registry, a package-manager CLI must meet ALL these criteria:

    1. Standalone binary available: The project must publish pre-built binaries (e.g., via GitHub Releases) that do not require a language runtime at install time.
    2. Deterministic verification: The binary must have a SHA256 checksum, GitHub asset digest, or attestation that can be pinned.
    3. No bootstrap toolchain: Installation must not require npm, pip, cargo, or go to be present on the user's system.

    Ineligible (Denied)

    If ANY of these apply, the CLI is not supported:

    1. Runtime-only distribution: The package is only available as an npm/pip/gem package with no standalone binary (e.g., requires npx or pip install).
    2. Non-deterministic install: The process pulls transitive dependencies at runtime without a lockfile or checksum pinning.
    3. Build-from-source only: The package requires compilation with a toolchain (e.g., cargo build) and lacks pre-built assets.

  3. How versioned installs are resolved

    main

    When you use the name@version syntax, nanobrew follows a specific resolution logic to determine if you are requesting a versioned formula or a pinned version:

    1. Versioned Formula Check: It first attempts to find an existing formula matching the full string name@spec (e.g., python@3.11). If found, it proceeds with the standard installation.
    2. Version Pin Check: If no formula matches, it checks if the <spec> part matches a version pattern (e.g., 0.17.0). If it matches, it treats it as a version pin and attempts to resolve the specific bottle from the registry (GHCR).
    3. Failure: If neither matches, it returns a formula-not-found error.

    For Homebrew bottles, nanobrew matches the requested version against available tags in GHCR and selects the appropriate bottle based on your current platform's BOTTLE_TAG or BOTTLE_FALLBACKS.

  4. Understand the Nanobrew Bottle Pipeline design

    main

    Nanobrew is transitioning from a supply chain that depends entirely on Homebrew's infrastructure to a 'Native Bottle Pipeline'. The goal is to host and build binaries (bottles) directly, reducing dependence on Homebrew's GHCR and formula API while maintaining compatibility with Homebrew's formula DSL.

    The transition follows three phases:

    1. Phase 1 (Proxy): All bottle downloads flow through a *.nanobrew.<domain> URL. The bytes still come from Homebrew, but Nanobrew owns the URL, provides telemetry, and caches binaries in Cloudflare R2 to reduce upstream load.
    2. Phase 2 (Self-built): Nanobrew builds a curated set of high-traffic packages (e.g., jq, ripgrep, fzf) on its own CI runners and hosts the resulting binaries in R2. This removes Homebrew bytes from the path entirely.
    3. Phase 3 (Full Coverage): Scaling the self-built pipeline to cover the top-500 packages to reach ~90% of real-world install volume.

    Key Design Principles:

    • No Forking: Nanobrew does not fork homebrew-core; it continues to consume the existing upstream formula DSL.
    • No New Formats: It uses the existing upstream registry schema (registry/upstream.json).

  5. How the nb-bottles registry works

    main

    The nb-bottles registry is a custom OCI-based mirror hosted on GHCR (ghcr.io/justrach/nb-bottles/<package>). It provides two tiers of package availability:

    1. Tier 1 (Mirror): Byte-identical copies of Homebrew bottles pinned in src/upstream/registry_default.json. This acts as insurance against upstream deletions or renames. It uses the same sha256 digests, making it transparently trustworthy for nanobrew.
    2. Tier 2 (Repackage): Custom-built packages from github_release sources (e.g., ripgrep, fd, bat). These are re-laid out into a standard bottle format (<name>/<version>/bin/<binary>) and published to the namespace. These provide the fastest installation path via blob caching and COW materialization.

    Consumption Mechanisms:

    • Tier 1 is consumed via a whole-fleet redirect using the NANOBREW_BOTTLE_DOMAIN environment variable.
    • Tier 2 is consumed via direct URLs in the registry records (resolved.assets[].url).

  6. Understand nanobrew Trust Tiers

    main

    nanobrew uses a tiered system to communicate how much confidence can be placed in a package's ability to run on a specific platform and version. Trust is computed per (token, version, platform) triple.

    TierNameMeaningEvidence source
    0unknownmetadata parsed, nothing verified—
    1checksum-verifiedartifact bytes match a published sha256Homebrew API / tap / registry
    2source-verifiedupstream source + domains + verification path reviewed by a humanregistry record upstream.verified
    3install-verifieda real install of this exact version succeeded on this platform: artifacts landed, links resolved, binary executedCI matrix, maintainer attestation, or install telemetry

    Users can check a package's tier using nb info.

  7. Recommended order for upstream registry integration

    main

    When integrating discovered GitHub candidates into the nanobrew registry, follow this priority order to ensure stability and compatibility with existing installers:

    1. Casks with GitHub release URLs, SHA256, and simple artifacts: These map most directly to the existing cask installer. Popular app casks can be promoted using scripts/seed-upstream-casks.mjs based on Homebrew cask install analytics.
    2. Formulae with GitHub release URLs and SHA256: Use these as trusted repo/tag/checksum allowlist records. Inspect release assets before treating them as binary direct installs.
    3. Formulae with GitHub archive URLs and SHA256: These are suitable for a source-build track but do not support the fast bottle-style install path on their own.

    Verification Requirement: A candidate is not verified simply because Homebrew points to GitHub. Every registry record requires an explicit repo allowlist, asset matching rule, OS/arch support, and a checksum/signature/attestation policy.

  8. Understand nanobrew package distribution tiers

    main

    nanobrew uses two distinct distribution tiers to manage how software is delivered to users:

    • Tier 1 (Mirror): Byte-identical Homebrew bottles mirrored under the ghcr.io/justrach/nb-bottles/* namespace. These use the same digests as Homebrew, ensuring the registry's sha256 pins verify unchanged content. This tier is used for packages with complex dependency closures or copyleft licenses (e.g., python, node, openssl, git).
    • Tier 2 (Repackage): Upstream release binaries (like GitHub releases) that are re-laid-out into bottle form under the nanobrew namespace. These receive new digests recorded in the nanobrew registry. This tier is used for self-contained static binaries with permissive licenses (e.g., ripgrep, fd, bat, gh, uv).

    All artifacts are content-addressed via sha256. The nanobrew client refuses any blob whose digest does not match the pin in the registry.

  9. How nanobrew release channels work

    main

    nanobrew maintains distinct channels for binaries and registries to ensure stability for regular users.

    Binary Channels

    • Stable binary channel: Consists of non-prerelease GitHub Releases. This is the only channel promoted by nb update, the update banner, and the Homebrew formula (Formula/nanobrew.rb).
    • Beta binary channel: Consists of prerelease GitHub Releases. These are intended for manual installation from the release page or future explicit beta commands.

    Registry Channels

    • Stable registry channel: Uses registry/upstream.json on the main branch. Released nb binaries may fetch and cache this data for six hours.
    • Beta registry channel: Controlled via the NANOBREW_UPSTREAM_REGISTRY_URL environment variable. Use this for testing new resolver classes or unverified records.
    • Local/offline channel:
      • Set NANOBREW_DISABLE_UPSTREAM_REGISTRY_REMOTE=1 to use only the embedded fallback.
      • Set NANOBREW_DISABLE_UPSTREAM=1 to disable upstream registry resolution entirely.

  10. Verify package security and integrity with nanobrew

    main

    nanobrew ensures package safety through several layers of verification:

    1. Digest Pinning: Every asset is pinned by sha256 at registry-build time. The client verifies this digest on every download to prevent MITM attacks or tampered mirrors.
    2. Continuous Scanning: The project performs weekly rescans of the entire stored fleet against fresh CVE data using grype.
    3. Vulnerability Gates: Packages are scanned for vulnerabilities using SBOMs (generated via syft). A scan with High or Critical vulnerabilities will block the publishing process (the --gate high flag).
    4. Revocation and Fallback: If a vulnerability is discovered in a pinned version, nanobrew can revoke that pin. The client will then automatically install a fallback (the previous known-good version) and issue a warning. If no fallback is available, the installation fails closed for safety.

  11. Use shimmed installs for private dependencies

    main

    Shimmed installs are an experimental mode for packages that have dependencies which provide command-line tools you do not want exposed globally.

    When using --shims, the requested formula gets wrapper shims in /opt/nanobrew/prefix/bin, but its dependency executables are kept out of the global prefix/bin. They are only added to the wrapper's private PATH. This allows tools like deno or python to be available to the requested tool without becoming first-class shell commands.

    You can also enable this mode via the environment variable NANOBREW_SHIMS=1.

    nb install --shims yt-dlp

  12. Understand the nanobrew Upstream Registry

    main

    The Upstream Registry is a curated metadata layer that allows nanobrew to perform direct installs from trusted release sources (like GitHub Releases or resolved vendor URLs) instead of relying solely on Homebrew metadata.

    Registry Resolution Order

    When looking for package metadata, nanobrew checks sources in this order:

    1. Local Cache File: Located at /opt/nanobrew/cache/api/upstream-registry.json by default.
    2. Remote Registry URL: The hosted metadata at https://raw.githubusercontent.com/justrach/nanobrew/main/registry/upstream.json.
    3. Embedded Fallback: A snapshot compiled directly into the nb binary (src/upstream/registry_default.json).

    Key Concepts

    • Seeded Packages: Packages whose trusted upstream records are manually included in the embedded registry snapshot.
    • Formula Records: Can be backed by GitHub Releases, resolved vendor URLs, or Homebrew bottle locks. They include resolved version + URL + sha256 metadata and dependency lists.
    • Cask Records: Backed by GitHub Releases or resolved vendor URLs. They support various installation types including apps, fonts, installer scripts, and direct binary downloads.
    • Registry Channels: The main branch of the repository serves as the stable registry channel. Experimental or unverified records should be accessed via a specific beta URL.