Reference¶

Keeping a profile's inputs fresh, the configuration variables, host requirements, the pinned toolchain and the repository map.

Keeping inputs fresh¶

uv run tools/resolve.py plan kali-research       # what would change (no downloads)
uv run tools/resolve.py resolve kali-research    # re-pin; then review the diff and commit
uv run tools/resolve.py toolchain-pin --latest   # host tools; the Mac (toolchain gpg) or any OS with gpg

• Review every lock diff. Look for signer changes, URL hosts, TOFU entries and version jumps. The pin is only as good as the review.
• "latest" is never trusted blindly. Apple's "latest" IPSW is already macOS 27, so each macOS base filters on its major version. pin_build / pin_version in a base freezes it.
• team_id: null means "record and warn". Confirm the ID with the vendor, then pin it.
• After a toolchain bump, commit and re-run ./tools/bootstrap.sh on the Mac.

Useful options:

• resolve --skip-large pins the OS image from its published hash but doesn't download it now. The build fetches it later.
• verify --skip-image re-checks a profile's cached packages without the OS image.
• toolchain-pin --only gnupg or --only registry re-pins only GnuPG, or only zot and cosign.

Configuration¶

Requirements¶

• An Apple silicon Mac on macOS 26 or later. macOS 27 guests need a macOS 27 host.
• At most two macOS VMs running at once on one Mac. Apple's licence sets the limit and the Virtualization framework enforces it; Linux VMs don't count, and VMs from other apps (UTM, Parallels) do. A macOS build needs one free slot. build.sh and rhubarbtart check this and name the VMs that are running.
• Rosetta, for the Linux profiles that run x86_64 programs (nixos-research, kali-research): softwareupdate --install-rosetta --agree-to-license. A new Mac may not have it. The build and rhubarbtart check for it and stop with this command if it's missing.
• Free disk space for each profile you build; see Disk space.
• 8 GB of memory is enough. Every build and test in these docs ran on an M1 Mac with 8 GB, with guests set to the bases' default of 8 GB.
• gpg on whichever machine resolves NixOS/Kali profiles or runs toolchain-pin. Any OS works.
• Licensing: RhubarbTart is FSL-1.1-ALv2 (LICENSE.md). Tart 2.40.1 is also FSL-1.1-ALv2 (© OpenAI), so check your use is a "Permitted Purpose". Chrome and WARP are proprietary; NixOS allows them only by name. See THIRD-PARTY-NOTICES.md.

Disk space¶

Measured on an M1 Mac with 8 GB of memory (October 2026). Sizes are what du reports; a macOS image is a copy-on-write clone of its vanilla VM, so the two together can use less than the sum.

So plan for about 25 GB for Kali, 12 GB for NixOS, 70 to 85 GB for the first macOS profile on a macOS version, and about 30 GB for each further macOS profile on the same version. A clone starts as a copy-on-write copy of its image, using almost no space, and grows as you use it, up to the profile's disk size (60 to 80 GB; 40 GB for juiceshop-target). The smoke test's clone is deleted after each build.

Nothing is deleted for you: rhubarbtart never deletes images. Space builds up from:

• Outdated images. After a lock changes, ./rhubarbtart images shows the old image as outdated. Move its clones on with rhubarbtart reset NAME, then delete it with tart delete rbt-…. A clone keeps working after its image is deleted; list then shows image-deleted.
• -unverified images left by a failed build. Delete them with tart delete once you've looked inside; a new build replaces them anyway.
• Old vanilla VMs (rbt-<base>-<build>-vanilla), once no current macOS profile uses that build. The next build of that macOS version reinstalls it.
• Old downloads in cache/artifacts/, filed by hash. Delete the folders whose hash no lock in locks/ mentions. Be careful with the rest: a build downloads what its lock needs again, but some vendors remove old releases (Chrome keeps only recent ones). If a cached file is the only copy left, deleting it means re-resolving the lock before the next build.

Each image also has a keychain entry under its name (service RhubarbTart). After deleting an image, remove it with security delete-generic-password -s RhubarbTart -a rbt-…, unless a clone still uses the image's password (list shows inherited).

Toolchain¶

config/toolchain.env pins the version, URL and SHA256 of each host tool, and tools/bootstrap.sh installs them into the git-ignored .toolchain/:

• scripts/env.sh puts .toolchain/bin first on PATH, sets PACKER_PLUGIN_PATH, sets CHECKPOINT_DISABLE=1 (no Packer phone-home), and pins uv to its own managed Python 3.13.
• preflight fails if a tool resolves outside .toolchain/, a version is off, or the pins changed since the last bootstrap.
• toolchain-pin --latest re-derives every hash and only accepts it when two upstream views agree.
• Textual is the TUI's only third-party dependency. It is not a bootstrap binary. It is pinned to an exact version in tools/rhubarb_tui.py's PEP 723 header and hash-locked in tools/rhubarb_tui.py.lock (uv lock --script); ./rhubarbtart-tui runs under uv run --script, which installs it from that lock and verifies every file's sha256 (the --require-hashes equivalent). The headless render test tools/test_rhubarb_tui.py pins the same version in its own tools/test_rhubarb_tui.py.lock.
• Zensical builds the documentation site and nothing else. It is pinned in tools/docs_site.py and hash-locked in tools/docs_site.py.lock the same way.
• check.sh asserts that the pins and all three locks stay consistent.

Repository map¶