Skip to content

feat(packaging): the macOS system install, a package that does the privileged setup - #2977

Draft
bryan-minimal wants to merge 19 commits into
pr2/shared-box-name-servicefrom
pr3/macos-pkg
Draft

bryan-minimal wants to merge 19 commits into
pr2/shared-box-name-servicefrom
pr3/macos-pkg

Conversation

@bryan-minimal

@bryan-minimal bryan-minimal commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

A macOS package that installs minimal machine-wide and does the privileged setup at install time, so a fleet can push it by MDM with nobody logged in (gominimal/inbox#1179). The curl installer stays the per-user path.

Stacked on #2976 (the shared box-name service). Draft until the release workflow can sign it; see "Not done" below.

What it installs

Where What
/usr/local/bin, /usr/local/lib, /usr/local/share/minimal min, its libraries and the guest images, from a staged release's manifest, each file checksum-checked as the curl installer does
/Library/PrivilegedHelperTools the box-name service's bundle (Minimal.app), behind a Developer ID check
/Library/LaunchDaemons dev.gominimal.zone (the name service, as the role account _minimal) and dev.minimal.local-range (the loopback range at boot)
/etc/resolver/min.internal the scoped resolver file
/Library/Application Support/minimal uninstall.sh and the record it works from

The postinstall does what min finalize-install does for one user. The first install admits every administrator to the _minimal group; dseditgroup adds a user.

The rules the scripts keep

  • Root reads nothing from /usr/local. Homebrew on older Macs leaves it user-owned, so everything root runs or trusts comes from root-only locations. A journey plants decoys there during the install and checks launchd runs the package's own program.
  • Both of the service's sockets are launchd's (Sockets in the plist). No local program can take UDP 7656 while the job is loaded, through an upgrade included.
  • A failed install fails closed and can be removed. A postinstall that cannot finish leaves no resolver file, starts the previous service again on an upgrade, and uninstall.sh works from its own record when there is no receipt.
  • It says why. A held port, a service an administrator switched off, and another program answering on the port each stop with a line naming the cause and the command to run.
  • The build trusts the download bucket for less. build-pkg.sh checks the Developer ID team on the downloaded min, refuses symlinks out of the stage, and names an unsigned build -unsigned.pkg.

Proof

Every night the farm (gominimal/minfarm) rebases this branch onto main, builds the package, and runs it in fresh macOS VMs. On 2026-11-16, on main f7b6e364, the build and 16 package journeys passed:

  • install, first use, uninstall on macOS 27 and 26 (vm-pkg-upstream, vm26-pkg-upstream), from a disk image, as a second user, after a reboot, reinstall after uninstall
  • upgrade from the previous build, upgrade with a user's loop asking for the port throughout (0 binds)
  • the failure paths: port held (UDP, TCP, across a reboot, recovery), service switched off, a failed first install then uninstall, another program answering on the port, a user-owned /usr/local with decoys

Also: minimal's Linux PR gates on this stack in the farm's Linux lane (13 of 13 steps), scripts/install_test.sh with the darwin+pkg case, shellcheck on the four scripts.

Reviewed in the farm over 18 rounds against a local-user threat model (a user in or out of the admitted group, against root and against each other). Every finding is fixed and has a journey, except one noted below. Peers (Docker, OrbStack, Tailscale, Podman, Apple container, Determinate Nix) and Apple's guidance are compared in the farm's docs/research/macos-pkg-peers-and-apple-guidance.md.

Not done, and not proven

  • No signed build has been tested. Every journey ran an ad-hoc test build (build-pkg.sh --with). Unverified on a signed, notarized release: the developer name in Login Items, hardened runtime on executables other than min, and whether the release runner's package lists AppleDouble ._* entries (a build in an operator's session lists 45; none reach the disk).
  • The release workflow does not build the package yet. release.yml signs binaries on the minimal-signing runner; it needs a job that runs build-pkg.sh --sign --notarize, and a Developer ID Installer certificate there.
  • The Service Management profile in the README is untested. Apple delivers that payload by MDM only.
  • Linux: the "is the answer on the port the package's service" check is macOS only (launchd); the systemd half is not written.
  • Product questions are in packaging/macos/pkg/README.md, "Still open": which min wins beside a curl install, the fleet's admission policy, install.toml method = "pkg" (gominimal/inbox#1168), running sessions across an upgrade, Full Disk Access for removing the role account.

Reading order

  1. packaging/macos/pkg/README.md: what an admin is told.
  2. scripts/preinstall, scripts/postinstall, scripts/uninstall.sh: what root runs (about 500 lines).
  3. build-pkg.sh: what the signing machine runs.
  4. The Rust: crates/switch (where the switch binary may come from), crates/minvmd/src/cmd/answerer.rs (launchd's unbound socket), crates/minimal/src/resolver.rs (who answers on the port).

🤖 Generated with Claude Code

@coderabbitai

coderabbitai Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@bryan-minimal

Copy link
Copy Markdown
Member Author

Prepush on anvil for abc73fc (job 01829, the CI mirror on the three-PR stack: fmt, clippy, nextest, miri, kani 31m, actionlint, shellcheck): green except cargo-machete, which #2872 clears. Skipped on the box as on PR 1 and PR 2: minimald-root-integration (no sudo), apparmor-profile (no apparmor_parser), and the KVM lane (the mr matrices stand in).

bryan-minimal and others added 18 commits November 16, 2026 13:22
…ivileged setup

A component package (pkgbuild, wrapped by productbuild) installs minimal
machine-wide under /usr/local from a staged release's components manifest,
every file checksum-checked as the installer does; a fleet deploys it by
MDM (gominimal/inbox#1179), and the curl installer stays the per-user path.
Its postinstall does what `min finalize-install` does for a user, with
nobody logged in: the box-name service's bundle under
/Library/PrivilegedHelperTools behind the Developer ID check, the resolver
file for min.internal, the boot-time loopback-range job, and the service
under a role account, `_minimal`, admitting the members of its group (every
administrator at the first install; `dseditgroup` adds a user). preinstall
stops the services for an upgrade; a postinstall that fails starts the
previous ones again. uninstall.sh undoes all of it, account and group
included, then removes every file in the receipt and the receipt, leaving
/usr/local's standard directories. `build-pkg.sh --with` makes a test build
from this tree, ad-hoc signed and named as such. The curl uninstaller leaves
a package-installed Mac's DNS setup to the package.

Three review rounds and the farm's package journeys and probes are behind
this; the open questions are in packaging/macos/pkg/README.md.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…the notarize step

Review of the package for an MDM pilot and for the day the Developer ID
Installer certificate arrives found three gaps in build-pkg.sh:

- No Distribution of its own: productbuild's synthesis said
  hostArchitectures="x86_64,arm64" for an arm64-only payload, set no
  minimum macOS, and left the install domain open. The script now
  synthesizes the Distribution and gives it what the synthesis leaves out:
  arm64 only, rootVolumeOnly, the local-system domain, a minimum macOS
  (`--min-os`, default 15.0), a title.
- No component plist: pkgbuild's own analysis marks every bundle
  relocatable, and Installer follows an older copy of the same bundle
  identifier elsewhere on the disk. The analysis is kept and
  BundleIsRelocatable set false for each bundle found (the key is absent
  when true, so it is added).
- No notarization: `--notarize PROFILE` submits with notarytool, waits,
  staples, and runs the Gatekeeper assessment. `--sign` is timestamped
  and checked back with pkgutil. A test build is refused a signature
  instead of noted.

The postinstall's install.log line for a user with an older curl `min`
now says the older uninstaller's root commands about the host DNS setup
are not to be run (the farm saw 0.7.2's uninstaller print them beside the
package). The README gains "Deploying through an MDM" and "Signing and
notarizing", and one more open item (test builds' 0.0.0 bundle versions).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…download page

One read-only compressed volume named Minimal with the package alone at
its top; --sign-dmg signs it with the Developer ID Application identity
and --notarize notarizes and staples it as it does the package. An MDM
takes the package, a person the image.
The macOS package places gvproxy-min in /usr/local/bin, since macOS seals
/usr/bin, but the resolver probed only the user's bin directory, /usr/bin and
/usr/lib/minimal/bin. A Mac installed from the package alone therefore found no
switch and minvmd logged "booting without guest egress".

The package lookup now takes the first existing of /usr/bin/gvproxy-min and
/usr/local/bin/gvproxy-min. Order is unchanged elsewhere: a user-local install
still wins, and a Linux package's copy wins where both exist.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…t over unbound

When another program holds UDP 127.0.0.1:7656 as the service is loaded,
launchd's bind fails and it still starts minzoned with the socket it made: a
datagram socket with no address. launchd reuses that socket for every later
start, so box names went unanswered after the other program left, until a
reboot or a reinstall.

The service now checks the listener's own address. With port 0 it binds the
hook port itself. While the port is still held the bind fails, the error names
the port, and the service exits, so the manager's next start after the port is
free answers.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…d stands

The name service now exits while another program holds UDP 7656 and answers on
its first start after the port is free, so the postinstall's five-second start
check failed the whole install in that case. The postinstall now looks for the
port's holder: with one, it prints the program and its pid, says box names
resolve once it stops, and the install succeeds. With none, the check fails
the install as before.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… root alone can change it

b1418b5 added /usr/local/bin/gvproxy-min to the lookup with an existence
test only, on every platform. On a Mac whose /usr/local/bin belongs to a user
(Homebrew's Intel layout), and on Linux hosts where a group can write it, any
file there is someone else's to replace, and the daemons of every other user
would run it.

The path is offered on macOS only, and only when the file and its directory
are root's and closed to group and others, and the file is no link. Where
that does not hold the lookup goes on as before the earlier change, to the
operator's path.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ls, and leaves no resolver file

86689af let an install stand when another program held UDP 7656, because the
service takes the port by itself once it is free. But the resolver file was
already written, the port is unprivileged, and so the program holding it, run
by any local user, answered every user's box names; under MDM the install
reported success.

The resolver file is now written last, once the service holds the port. When
the service is not running after its five seconds, an earlier install's file
is removed and the install fails, naming the holder, its pid and its user
when there is one. The service stays loaded and takes the port when it is
free; installing again writes the file.

Still open: every upgrade boots the service out in the preinstall, which
frees the port for the length of the payload's extraction.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…t install can be removed

Review findings A-1, A-3 and A-6 on the macOS package.

The postinstall read what to require of the service program's signature
from /usr/local/share/minimal/pkg-info and copied the program from
/usr/local/bin/Minimal.app. Where a user owns those directories (Homebrew's
Intel layout, Macs migrated from one) that user could change both between
the payload and the postinstall, and root's launchd jobs then ran the result.

- The payload puts the bundle at /Library/PrivilegedHelperTools/Minimal.app;
  the postinstall checks it there. The preinstall moves an earlier bundle
  aside, and a failed postinstall puts it back.
- build-pkg.sh writes the signing expectation, the channel and the test-build
  flag into the postinstall. pkg-info stays for a person to read.
- The uninstaller is installed by the postinstall, first, under
  /Library/Application Support/minimal with the list of the payload's files,
  and works from that list when there is no receipt.
- A first install that fails removes its services, bundle, resolver file and
  the account it made, and names the uninstaller.

The uninstall command changes:
  sudo "/Library/Application Support/minimal/uninstall.sh"

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… only

sudo keeps the caller's PATH on macOS, and /opt/homebrew/bin or a
user-owned /usr/local/bin is often first on it: the uninstaller would have
run whatever dscl, rm or launchctl it found there, as root.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…installer from /usr/local

Installer leaves files a newer package no longer carries, and they are in
no receipt afterwards: the farm's upgrade journey found
/usr/local/bin/Minimal.app and /usr/local/share/minimal/uninstall.sh still
there after an uninstall. The preinstall removes the two, only when the
earlier receipt lists them and neither is a link.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… says so, and changes nothing

A label an administrator disabled with launchctl stays disabled across an
uninstall. launchd then refused the postinstall's bootstrap with
"Bootstrap failed: 5: Input/output error": an upgrade had already replaced
the payload, and a fresh install was undone, neither saying why (minfarm
j-c69494a470346c4c). The preinstall now reads launchd's disabled list
first and stops before anything changes, naming the label and
`launchctl enable`. The postinstall's own line points at Login Items, the
other switch, which the disabled list may not show.

README: what a user sees with the service off, measured (minfarm
j-40efc69b5367bbcd): a box-name lookup hangs 60 s, other names are
unaffected.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The preinstall booted the box-name service out, and until the postinstall
loaded it again UDP 7656 was free with the earlier install's resolver file
still naming it. The port is unprivileged: a local user's loop took it
during an upgrade, answered for *.min.internal in that window, and the
upgrade then failed for every user (minfarm j-0a7aeb65f643ca23; review
finding A-2's upgrade half).

The job now stays loaded. When its definition is unchanged, which is every
upgrade so far within this layout, the postinstall restarts the process
with `kickstart -k` and launchd never lets go of either socket. When the
definition changed, the resolver file goes before the job is loaded anew
and is written again once the service holds the port, so the free moment
points nowhere. A failed upgrade restarts the earlier program and brings
the resolver file back only when that service is seen running on the port.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… when it does not answer

On a package install the names item waits on no daemon of the user's: a
system service serves the zone. With that service off (an administrator's
`launchctl disable`, or Login Items) the item read "waiting on a daemon
(no daemon is reachable to report the port its DNS service listens on)",
which sends the user to their own daemons (minfarm j-40efc69b5367bbcd).
When the installed unit is a shared service's and nothing answers on its
port, the cause now names that service, that names do not resolve, and
what an administrator runs to see why.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ile launchd holds its job

`min finalize-install --show` took any DNS reply on the hook's port as
the installed service answering. launchd makes the shared service's UDP
listener and holds it for as long as the job is loaded, so with the job
loaded nobody else can have the port (measured in a VM: a user's bind is
refused with every reuse option, the program running or stopped). With
the job booted out the port is any local program's, and with a stand-in
answering there the command said "Every part of the install is finished
on this machine" (farm job j-14638d60cf6734de).

On a Mac with the package's unit, the names item now also asks launchd
whether the job is loaded (`launchctl print`, which a standard user may
run). Not loaded: the item is listed under "can't do on this machine",
says the answer is not the package's service, and names `lsof` on the
port. A launchd that did not say is unconfirmed, never done. Linux is
unchanged: systemd holds the port the same way, but that is unmeasured.

Review finding F2, second half.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Three review findings in build-pkg.sh, all about what a changed bucket or
a passed-on file could do:

- The script runs the payload's `min` (for its version and completions)
  on the machine that holds the signing identity. The download matched
  the manifest's checksum, but both come from the same bucket. A
  downloaded `min` now runs only with minimal's Developer ID (team
  3G47C5HY64); one given with --with is the builder's own (A-4).
- A manifest symlink row's target was taken as written. It must now be a
  path inside the payload (not absolute, no `..`), and lead to a file
  the manifest staged (A-5).
- An unsigned build of a release was named as the release is. It is now
  minimal-<version>-unsigned.pkg; only the signed package has the plain
  name (A-7).

Checked: the released unstable min is accepted and the build of it ends
in ...-unsigned.pkg; an Apple-signed and an ad-hoc binary are refused by
the requirement; `/etc/passwd`, `../x`, `a/../b` and an empty target are
refused by the link rule, the two targets the manifests use are not.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… MDM

Apple's payload page lists com.apple.servicemanagement as device channel
only, requiring user-approved MDM, with no manual install. An admin who
tries the profile by hand on one Mac would otherwise read its silence as
the rule not matching.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… package

release.yml gains build-macos-pkg: after stage-installer, on the signing
runner, build-pkg.sh packages the staged row with the Developer ID Installer
identity, notarizes and staples it, and writes the disk image. The job is
skipped until the repository variable MACOS_PKG_INSTALLER_IDENTITY is set,
and nothing needs it, so a release is unchanged until the certificate is in
the signing keychain.

build-pkg.sh gains --notary-keychain: the runner keeps its notarytool
profile in the signing keychain, not the default one, and the script's
submit could not find it there.

Not run: the job needs the signing runner and a certificate it may not
hold yet. Checked here: shellcheck, the option's refusals, the workflow
parses as YAML.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant