From 5c499d290bc658d76318ec4671d0bffc6f59dbcc Mon Sep 17 00:00:00 2001 From: didericis Date: Mon, 27 Jul 2026 10:12:21 -0400 Subject: [PATCH] docs: record what the passing runs established MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both variants now pass, and the with-prerequisites run settled several things that were guesses before: * The Apple `container` service is per-user, confirmed directly rather than inferred: the throwaway account's appRoot is its own (/Users/bbtest/Library/Application Support/com.apple.container/), and starting it left the admin's service running and its agents intact. * Setting up a new account is two steps, not one. The guest kernel lives in that same per-user app root, so a fresh account has none and `container system start` prompts to download it — and only prompts, since the flags default to asking. Headless callers need --enable-kernel-install. * Neither step is performed by `bot-bottle backend setup --backend=macos-container`, which checks and then defers to `container system start`. So the real path for a new account is `container system start --enable-kernel-install`. * Any of it requires entering the user's launchd domain with `launchctl asuser`, because the apiserver is a per-user agent reached over XPC. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01WEfZZhakx13bxTfXcZCoS5 --- .../testing-clean-install-on-macos.md | 33 ++++++++++++++++--- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/research/testing-clean-install-on-macos.md b/docs/research/testing-clean-install-on-macos.md index 2bd36e33..1f101a59 100644 --- a/docs/research/testing-clean-install-on-macos.md +++ b/docs/research/testing-clean-install-on-macos.md @@ -237,10 +237,35 @@ service is per-user. It asserts the install is sound and *reports* backend readiness without failing on it, because install.sh provides no backend and so cannot regress one. -`test-ready` models a system **with** them: it runs `container system start` -for the throwaway user, then demands doctor go fully green, backend included. -(`bot-bottle backend setup --backend=macos-container` does not start the -service — it only checks and tells you to run that command yourself.) +`test-ready` models a system **with** them, then demands doctor go fully green, +backend included. Both variants pass as of this writing. + +### The per-user prerequisite is two steps, not one + +Running it revealed that "set up the backend for this account" is more than +starting a service: + +1. **`container system start`** — the service is per-user. The run confirms it + directly: the throwaway account's `appRoot` is + `/Users/bbtest/Library/Application Support/com.apple.container/`, its own, + and starting it left the admin's service untouched. +2. **A guest kernel**, which also lives in that per-user app root. A fresh + account has none, so `container system start` prompts to download one — + and *only* prompts, since the flags default to asking. Headless callers + must pass `--enable-kernel-install` or the command dies on + `failed to read user input`. + +Neither step is done by `bot-bottle backend setup --backend=macos-container`, +which only checks and then tells you to run `container system start` yourself. +So a new account's real path to a working backend is: +`container system start --enable-kernel-install`. + +The harness must also enter the user's launchd domain via +`launchctl asuser ` to do any of this. `container system start` registers +`com.apple.container.apiserver` as a per-user launchd agent and talks to it +over XPC; from plain `sudo -u` the caller is still in root's bootstrap +namespace, the lookup crosses domains, and the apiserver answers +`invalidState: "unauthorized request"` even though the agent started fine. It refuses to start against an existing account (a reused home is not a clean install), and it tears the account down from an `EXIT`/`INT` trap armed the