macOS provider reference
Development preview
This page describes a pinned development revision, not a published release. Its package version may still identify the preceding release while the next version is being prepared.
Use the operator guide for the implemented provider path. This document retains advanced commands and dated component/integration evidence; it is not an alternative installation checklist. Private rehearsal controllers isolate and restore the qualification Mac's existing deployment and are not shipped prerequisites. Older unfinished-gate statements below describe the scope of those rehearsals, not the latest release candidate. The summary below identifies the recorded delegated release acceptance; historical component checks remain separate evidence.
Current qualification
The merged macOS implementation has real Apple Silicon evidence for preparation, cold-boot Nix/Swift builds, service lifecycle and delegated release artifacts. The merge record b3848816 records end-to-end acceptance at 32f54fd5d2bee97c5f0ea07f50657cb680ae55c8: a coordinator delegated the build to the freshly installed Mac provider, and a dependent Linux job verified archive checksums and the guest export. See the macOS build log and Linux artifact verification log.
This establishes that release workflow at that revision, not an all-workflows pass on current master. The installer rehearsals below reused a dedicated quota volume and, in some cases, a separately qualified guest clone; they must not be described as one pristine installation test. Abrupt power loss, network changes, optional managed-cache publication and broader full-Xcode workloads are not established by these results. Managed-cache publication remains disabled in the minimal installation. The later network-quarantine diagnostic change 1d708ae9 adds diagnostic evidence, not automatic network recovery or transition acceptance.
Integrated qualification on 2026-10-24
- Native public preparation completed from the pinned, previously unprepared vanilla upstream cache: fresh accounts/keychain, guest Nix/tools, CLT, sealing, uncached Nix builds, Swift compile/run and a separate offline cold boot. Repeated preparation verified all nine checkpoints without rebuilding the guest. Evidence:
ngit-ci-fresh-rehearsal.6_w6xad5, guest sessionrun-QlqQso. - The first provider activation exposed an omitted no-managed-cache setting. The minimal installer does not provision a cache worker; generated settings now explicitly disable publication/inventory. A one-launch diagnostic confirmed the cause and allowed normal drain and exact baseline restoration.
- The corrected native release candidate passed fresh accounts/keychain and configuration creation, explicit prepared-guest import, checkpoint continuation, repeated preparation, first activation and provider readiness. Evidence:
ngit-ci-fresh-rehearsal.gvgso0viandngit-ci-fresh-resume.788a30vp. This second rehearsal reused an APFS clone of the guest qualified above, avoiding another large download; it is not a second pristine guest test. - The prepared-import candidate completed stop, repeated stop, qualified restart and first-install deactivation, followed by exact baseline restoration.
- Its first delegated allocation reached the fresh provider but timed out on all signed clone URLs before compilation. A read-only inspection found no explicit guest DNS servers. Native preparation now configures the reviewed public resolver and checks it during qualification. A separate retained-guest clone passed continuation, sealing and offline cold boot with the corrected recipe, reusing CLT without another download. Evidence:
ngit-ci-dns-guest.b32jyqmn, guest sessionrun-wwuHHo. Successful delegated artifacts remain a separate gate; the earlier startup failure is not a successful build. - The DNS-corrected candidate received allocation
1806e79107a4d173152365e67ca7741ef7b9a1d3ff2f24a6035833d5c6f9da54at commit7cfe983b9e683f0135bd751c7e41ee33dc5ff566. Repository cloning and NAR downloads succeeded, but realization failed when a local-store client tried to launch a builder from the private job directory. Its signed failure result is3824661dac0ad571aa73748533e1566501d7ddcd96208d45b960307e7d60260a. Preparation now gives ordinary clients the daemon store and explicitly keeps the daemon's backing store local. Qualification uses default client selection from a private working directory, rather than masking it with--store daemon. Native file transformation/retry/refusal checks passed. The corrected recipe then passed continuation, CLT reuse, sealing and a separate offline cold boot, including uncached default-client Nix builds from private working directories and Swift compile/run. Evidence:ngit-ci-store-json-guest.72xo9un2, guest sessionrun-25tRJG. Delegated artifact acceptance is recorded separately in current qualification; these guest checks alone do not establish it. - Release packaging verified signatures, system-only dynamic libraries, system-PATH startup, archive manifests and guest export. The host retained Nix for building these test artifacts, but native installation/runtime operations did not use it. The latest setup suite passed 185 library, four CLI and six integration tests on Linux, plus strict all-target Clippy. Native focused socket tests passed; this does not claim that every test runs unprivileged inside a macOS Nix build sandbox.
The qualification machine reused its dedicated quota volume and retained upstream cache. Fresh APFS creation, recovery and cleanup were tested separately. Existing personal resources were not adopted. Final delegated-candidate artifact results are recorded in current qualification; neither process startup, successful lifecycle checks nor an older green workflow proves that the corrected candidate can complete the release workflow.
The delegated release rehearsal at b13bbe216aa241f2268f9f5b8988e2c21f3211f1 passed on 2026-10-22. That does not qualify every scenario below. Native keychain creation/unlock in a persistent launchd security session, guest bootstrap ownership, and explicit daemon/client Nix-store selection were necessary during the rehearsal; the source plists and manual steps alone do not reproduce it.
Read-only installation intent
The provider installer explicitly disables managed cache publication and inventory: it does not provision the separate cache worker. Guests can still download from their configured upstream Nix caches. Artifact uploads are unaffected.
ngit-ci-macos-setup install-plan --config installation.json validates schema 1 and prints a JSON plan without sudo, network access, host inspection or changes. It also runs on Linux for configuration review. Exit zero means valid intent, not install readiness: ready_to_apply is always false and every resource is blocked pending verification. Provider-only provisioning uses install-prepare, followed by install-activate; planning alone never performs either operation. The existing plan --role command remains an account-only plan.
Example for a coordinator (the repeated hashes are placeholders, not a release):
json
{
"schema": 1,
"role": "coordinator",
"release_manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bundles": {"coordinator": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"},
"identity_refs": {"coordinator": "local-coordinator"},
"reuse": [],
"coordinator": {"providers": []}
}The input is a regular file of at most 64 KiB; a final symlink is refused. Unknown fields and schema versions are rejected. Fields are:
| Field | Meaning |
|---|---|
role | provider, coordinator or both. Include only corresponding role settings. |
release_manifest_sha256 | Release manifest digest; publisher authenticity is not checked by this command. |
bundles | Manifest digests keyed by exactly the required components: coordinator, or adapter/provider, or all three. |
identity_refs | Non-secret labels for coordinator/provider credentials; no adapter identity. Labels use 1–64 ASCII letters, digits, -_.; roles must use different labels. Never supply secret values. |
reuse | Explicit resource reuse intentions: selected-role coordinator-account, coordinator-home, discovery-account, discovery-home, discovery-socket, provider-account, provider-home, adapter-account, adapter-home, plus provider tart, softnet, storage. Omitted resources have create intent. No ownership or compatibility is inferred. |
coordinator.providers | Unique provider public keys; may be empty while awaiting approval. |
provider.coordinators | Unique coordinator public keys; must be nonempty for provider-only setup. |
provider.vcpus, memory_mib, storage_mib | Positive shared job budgets; all image offerings share these allocations. Physical capacity and space needed for templates/rollback remain unchecked. |
provider.host_memory_reserve_mib | At least 4096 MiB reserved for the host, separate from job RAM. |
provider.max_jobs | Exactly 1 in this version. |
provider.images | One to three entries, each with family (vanilla, base, xcode), upstream_sha256 and intent (create or reuse). Each family occurs at most once; vanilla is optional. |
Digests and public keys use 64 lowercase hexadecimal characters, without a sha256: prefix. Public keys receive syntax validation only; this does not verify curve membership or authorization. Image digests identify the upstream OCI manifest, never the locally prepared disk. The provider preparation path supports one freshly prepared vanilla image; the wider planning schema does not imply that every image family or combined role has an installer.
For both, an empty remote trust list is valid and local_pairing: true records intent to enroll the distinct local identities in each other. Planning does not enroll either service or grant repository/secrets access. Identity labels are not resolved and are omitted from output; parse errors do not echo input values.
The plan describes intent rather than installed resources. Endpoint reachability, authenticated inputs, Tart/Softnet versions and licences, host preflight and resource ownership require separate checks during preparation and activation. Consumers must never interpret successful parsing as authorization to mutate the host.
Connection settings and repository scope
Schema 1 accepts an optional connections object. Omitting it retains the incomplete planning mode; supplying it validates its settings before any plan or definition is emitted. For example, add these fields to a coordinator configuration (the public key below is only a syntax placeholder):
json
{
"connections": {
"relays": ["wss://relay.example.com"],
"blossom_servers": ["https://artifacts.example.com"]
},
"coordinator": {
"providers": [],
"repositories": [
{"pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "identifier": "my-project"}
]
}
}Connections require at least one wss:// relay. A provider also requires at least one https:// artifact server; coordinator-only artifact servers may be empty. Each list permits at most 16 URLs of at most 2048 bytes. URLs are normalized, duplicates after normalization rejected, and paths retained. Credentials, query strings, fragments, whitespace, backslashes and literal comma delimiters are rejected without echoing the URL in errors. Do not put secrets in URL paths; accepted endpoint URLs appear in definition output. This command does not contact the endpoints or establish their availability or trust.
Provider and combined installations may set connections.provider_blossom_timeout_seconds to a positive integer, for example 7200 for a two-hour per-attempt transfer deadline. It maps to the existing NGIT_CI_PROVIDER_BLOSSOM_TIMEOUT_SECS setting in the provider's private configuration; omission preserves the provider default. Coordinator-only plans reject it. Choose this before preparation: retries retain the recorded setting and refuse a changed value rather than silently changing a live installation. See provider artifact transfer budgets for defaults and retry costs. Allow for the largest artifact and the site's upload speed, not just the small host binaries. The qualified guest-tools archive is about 454 MB: at a steady 1 Mbit/s upload rate it takes about 61 minutes before protocol overhead. The choices example allows two hours per attempt; slower or unstable links need a larger reviewed budget. A timeout can restart the entire upload, and graceful maintenance may wait for artifact publication as well as compilation. Also review the coordinator's result-finalization allowance.
A coordinator with connection settings must select repositories. Each entry uses a lowercase hex pubkey plus an exact identifier. Watching every repository of an author requires an explicit all_repositories: true and no identifier; omitting an identifier alone is an error. Exact and author-wide selection are mutually exclusive. Empty identifiers, whitespace, controls, commas, # aliases and duplicate entries are rejected so serialization cannot broaden the scope or create secret aliases. Public-key validation remains syntactic; authorization and curve validation belong to runtime validation before activation.
Generated coordinator configuration uses NGIT_CI_ACT_RUNNER=none for delegated Nix jobs, request-required execution policy when connections are supplied, and an empty secret-provider allowlist. It does not enable Docker/act jobs locally or grant repository/secrets authorization. Connection settings reach the coordinator and provider only; discovery remains credential-free and receives no relay settings. Empty provider trust and unresolved local pairing still block a runnable setup.
At 285c1f2, native validation on Apple Silicon macOS 27.0.1 passed 64 library tests, 2 CLI unit tests, 3 CLI integration tests and strict all-target Clippy. This includes native metadata collection, plist conversion and read-only configuration/definition commands. Account/home lifecycle fault tests use test doubles; this run created no live accounts, activated no services and changed no VM images. Linux passed 60 library, 2 CLI unit and 2 integration tests plus strict Clippy. Fresh-install and initial activation acceptance remain outstanding.
Initial service definitions (review only)
ngit-ci-macos-setup install-service-definitions --config installation.json prints JSON plist dictionaries and unresolved prerequisites. Provider selection produces adapter/provider definitions; coordinator selection produces coordinator/discovery definitions; both produces all four. Executables reference the selected immutable bundle paths. The discovery executable belongs to the coordinator bundle and needs no signing identity.
All definitions have Disabled: true and RunAtLoad: false. The command writes no files, registers no services and does not resolve credentials. These are incomplete configuration previews, not files to copy into LaunchDaemons: relay/artifact endpoints and repository scope when omitted, state/work paths, protected-address policy, runtime/template bindings and credential provisioning must be generated and validated before activation. No full first-install or local pairing claim is made. Do not enable these previews manually.
Fresh account plan/apply --role coordinator now includes a separate ngit-ci-discovery user/group and mode-0700 home; both includes four users. Receipt-backed retry, identity checks and guarded removal apply to this account too. Older coordinator receipts remain readable/removable; extending them requires a reviewed migration, and apply refuses the changed role set. The existing isolated rehearse command retains its coordinator-only fixture.
The proposed coordinator process uses the discovery effective group for access to its socket. The worker owns a separate socket directory (0750) and creates its socket as 0660; each service's private home remains accessible only to its owner. The worker receives no coordinator/provider signing environment or credential references. These permissions and startup ordering still need native service qualification; socket-directory provisioning is available below; activation remains unimplemented. Registered coordinator or discovery services block removal of either account. Secret-bearing delegation remains explicitly empty, including for local pairing.
Discovery socket directory lifecycle
After provisioning the discovery account, discovery-socket-apply creates only /var/lib/ngit-ci-discovery-socket, owned by that account and its primary group, mode 0750. It requires interactive administrator access. It starts no service, creates no socket, and changes neither the provider nor adapter. The discovery worker creates and removes worker.sock itself (mode 0660).
The command uses the production account receipt and lock. Receipt schema 3 adds a separate discovery_socket directory record; schema 1/2 receipts remain readable. The worker's mode-0700 home remains a different resource. Intent is checkpointed before creation, an inode/device identity is saved before publication, and retry verifies that identity. Publication never replaces an existing directory. Existing compatible directories require --reuse-existing; they remain externally owned and are never removed by setup. Older setup versions cannot process schema 3; retain the matching setup binary with the receipt.
discovery-socket-remove removes only the receipt-owned empty directory after coordinator/discovery services and worker processes stop. A lingering socket or any file blocks removal; it does not unlink sockets or recursively delete data. Let the worker shut down cleanly and review any retained contents before retrying. Both commands reject changed identities/permissions and require the recorded service account to remain valid. Account removal is blocked while its socket directory remains, including an externally reused directory or a recreated path. Read the non-secret checkpoint with the existing status command.
These are native lifecycle primitives, not yet the unified installer. Separate-user coordinator-to-worker socket access and startup ordering still need a privileged service rehearsal; unit fault tests and temporary-directory filesystem tests do not establish that acceptance.
Host preflight
ngit-ci-macos-setup install-preflight --config installation.json is an unprivileged macOS-only check. It reads the same bounded input, then obtains OS version, Apple Silicon capability, logical CPUs and physical RAM with native sysctl calls, and APFS type/available bytes for /System/Volumes/Data with statfs. It does not enumerate directories, inspect personal files, download anything or modify service state. No developer command-line tools are required by the probe.
Output contains host, named checks, and the still-blocked installation plan. Failed checks return nonzero after printing the report; unavailable metadata fails with an error. Successful checks do not authorize installation. Current release preflight requires Apple Silicon and macOS 26 or later. Provider checks also require CPU/RAM budgets to fit (including host RAM reserve) and APFS storage. A new storage budget must fit available Data-volume bytes; explicit storage reuse skips that comparison because its existing volume has not yet been inspected.
Availability is a point-in-time measurement, not a reservation or a claim that purgeable storage is free. Template/rollback overhead, existing volume quotas, account/receipt ownership, runtime compatibility and provenance remain blockers. The probe does not subtract previously allocated CI storage from a new budget, or assume that all requested storage is immediately allocated.
Installer gap review and implementation order
Review date: 2026-10-23, after native template-worker acceptance at 00abd8d. This is a source audit, not another implementation expansion. The latest operator batch passed template-worker apply/retry/verify, changed-pin/wrong-path/empty-selection refusal, exact disposable cleanup and restoration of the original services. The cached source and original settings remained unchanged.
Assessment: the resource components are substantially implemented and tested; the product path for a new operator is still incomplete. There is no public CLI single guided command composing preparation through first activation. Subsequent implementation connects native fresh preparation to install-prepare as described below; complete release acceptance is still pending. Counting component tests or source files would overstate completion. Keep the existing work; do not rewrite account, keychain, storage or import machinery.
A further handover constraint was confirmed on 2026-10-24: the established Mac provider has no installer account receipt. Although low-level account/home helpers support explicit external reuse, the composed keychain and setup-session lifecycle requires installer-created ownership. Do not manufacture an ownership receipt or remove that guard to qualify the installer on this host. A clean first-install rehearsal therefore needs a reviewed handover preserving the legacy identities, credentials, image cache and rollback, or a clean supported host. Existing-service replacement/stop/start acceptance does not establish that first-install gate.
The fresh-source library now validates a cached upstream OCI manifest against its selected digest and can create a separate raw-image clone using pinned Tart, with automatic pruning disabled. The caller must first verify Tart and record a unique destination; an existing destination is refused rather than overwritten. This path trusts the operator-owned decompressed cache: validating the manifest is not verification of every cached disk block. It preserves the portable upstream digest in environment identity and does not hash the mutable prepared image. Native cached clone acceptance passed on the qualification Mac, with unchanged production PIDs and original cache. The guest-image boundary also has a native read-only inspection path: it selects Data only from an APFS container whose physical stores all belong to its main Apple_APFS partition, retains recovery metadata and uses non-forced detach. Synthesized APFS devices are recognized but never used as physical-store authorization; ISC and Recovery partitions are excluded. Host-container and ambiguous-volume refusal cases are unit-tested. Native read-only attachment, fixed guest system metadata inspection and detach passed twice on the fresh clone; production PIDs stayed unchanged.
Offline seeding now writes authenticated guest inputs and fixed bootstrap paths through an ownership-enabled Data mount. Existing files must match content, owner and mode; conflicts are preserved. The guest Nix recipe creates its own store volume, records its UUID for a mount daemon and uses NIX_VOLUME_CREATE=0 to avoid headless vifs failures. Bootstrap requires an explicit start after RPC readiness, and a partial installation refuses automatic reexecution. Daemon readiness is probed for up to 120 seconds, with each client attempt bounded to ten seconds; the installer returning does not itself prove the daemon socket is ready. Native seed and content-verified retry passed on the fresh clone, with unchanged production PIDs and no VM boot. This used the retained rehearsal guest-tools archive, not a new release candidate. The first guest Nix installation completed, but its immediate daemon socket probe failed. An explicit continuation verified the retained store, imported the pinned tools and passed a daemon connection check; the preparation VM stopped and the original host services were restored. The resulting rehearsal profile reports Nix 2.34.7, replacing the bootstrap installer's Nix 2.35.3. This does not yet validate the bounded readiness fix on a fresh installation. A subsequent cold boot passed automatic store mounting, daemon readiness and a unique uncached daemon build with root-owned mode-0700 HOME and TMPDIR, with guest network access blocked. The subsequent headless CLT installation reported package 26.6.0.0.1781586589, SDK 26.5 and Swift 6.3.3. Swift compiled and ran before and after removal of the dedicated preparation payloads; the second boot repeated the private-directory daemon build with guest networking blocked. Original host services were restored. This establishes the private rehearsal procedure, not acceptance of the complete public installer or a current release candidate.
The shipped recipe now includes explicit, non-automatic guest-resume and guest-clt launch jobs. Resume verifies the existing store and imports the pinned tools without recreating the volume or rerunning the Nix installer. CLT selection accepts only stable CLT labels actually offered by Software Update; it never installs all updates or opens a GUI fallback. The retained /usr/local/libexec/ngit-ci-qualify-guest script repeats daemon and Swift checks without needing preparation archives. Its receipt proves in-guest checks only; the parent supervisor must establish cold boot and blocked networking. The public host orchestration is still incomplete.
The guest-tools profile now also carries the native setup executable. Its internal guest-seal --recipe <digest> operation requires the matching guest marker, qualification receipt and CLT completion marker. It validates the generated job definitions and a bounded preparation tree, refuses running setup jobs, then checkpoints cleanup in /var/db/ngit-ci-template-sealing.json. Retry may finish only that same recipe's interrupted cleanup. It retains installed Nix/tools, root RPC, the store mount job and the standalone qualification script. This native replacement passed administrator acceptance on the retained preparation clone on 2026-10-24, including a separate offline boot after cleanup.
The internal native preparation worker now sequences three bounded VM sessions: Nix setup or explicit continuation offline; CLT, qualification and cleanup with reviewed Apple download exceptions; then qualification after a separate offline cold boot. It uses the authenticated runtime/dependency bundles, restricted Softnet helper and dedicated adapter identity, holds the Tart lifecycle lock, and refuses registered production services or retained job clones. Every normal error path attempts shutdown of only its selected ngit-ci-prepare-<UUID> clone; an unconfirmed stop is an error, never permission to resume production. Preparation-only socket cleanup takes Tart's storage flock and VM configuration record lock, then removes control.sock only after a nonblocking probe returns connection refused and the socket identity is unchanged. It runs before preparation boots and after confirmed shutdown. Live/uncertain sockets, snapshots and overlays remain failures; normal runtime template admission is not relaxed.
The internal root session supervisor runs that worker through launchd with SessionCreate and wake protection. It retains request/definition/log evidence, streams changing guest progress, and reattaches only to the same saved request and definition after a lost terminal. Requests explicitly bound the CLT download and installation deadline (5 minutes to 12 hours); allow at least four hours on slow links. This supervisor never drains or starts production services. Its caller must authenticate inputs, own and seed the clone, verify prepared account resources and hold the installation lock. install-prepare now composes these steps for a selected fresh vanilla image; combined administrator acceptance of that public path remains open. Internal commands are not an operator shortcut.
Native continuation acceptance passed on 2026-10-24 using host supervisor 2845f86: existing Nix-store continuation and pinned profile import, CLT reuse (package 26.6.0.0.1781586589), Swift 6.3.3 compilation/execution, native sealing, then a distinct offline cold boot with a new uncached private-directory daemon build and Swift compilation/execution. All three preparation VMs stopped, stale control sockets were removed under Tart locks, and the original provider baseline was restored. Evidence: ngit-ci-native-guest.ecnit07g and launchd session run-dLTk9j. This tests the native continuation/finish path against an installed store and CLT; fresh upstream first installation and complete public installer acceptance remain open. Overlapping progress tails can repeat prior log lines; the offline qualification used a distinct build ID from the preceding boot.
Minimum provider release boundary
The recommended first target is one Apple Silicon provider, one vanilla-based offering and one concurrent job, connected to an existing VPS coordinator. Download verification and coordinator public-key approval can be explicit documented steps. A small terminal helper may accept a few options or a documented config; a rich wizard is not a release gate. Retain existing advanced role and image APIs, but do not require new base/Xcode qualification or polished local-coordinator setup before this path works. This narrows the earlier aspirational delivery table in the operator design; it does not remove code.
A new operator must not need this checkout's private setup scripts, host Nix, Rust, Homebrew or Python from Apple developer tools. Downloading and preparing one guest remains necessary: a guide cannot simply ask a fresh operator to reuse the prepared image that happens to exist on our qualification Mac.
Historical gap audit and completion gates
This audit preceded the integrated qualification above. It explains the frozen implementation scope; it is not a current task counter or delivery estimate.
| Work package | Existing foundation | Missing implementation | Acceptance gate | Size / uncertainty |
|---|---|---|---|---|
| 1. Public setup entry point and release inputs | install-plan, install-preflight, install-prepare, release manifests and archive verification | Finish the small operator input flow; connect verified project and third-party inputs and licence acknowledgement. Verification/manual download instructions can replace an automatic release browser initially. | Start from extracted authenticated release artifacts and documented inputs, without a source checkout or development tools. | Medium; mostly wiring, not a new framework. |
| 2. Runnable initial host configuration and activation | Prepared-resource verification, runnable provider definitions, owned socket/log paths and install-activate; replacement/rollback of an existing pair | Code is connected; qualify first activation and recovery on the complete release candidate, including prepared-resource verification and startup permissions. | Install into absent service definitions; adapter qualifies before provider admission; a failed first start leaves a documented recoverable state. | Medium–large; integration must cover resources that component rehearsals never selected live. |
| 3. Fresh vanilla guest preparation | Native acquisition, seeding, finish/seal/offline qualification and intent checkpoints connected to install-prepare; continuation/finish accepted on hardware | Qualify current first installation from an unprepared upstream image through the public path, including recovery and owned-session cleanup. | Produce a ready guest from an unprepared upstream image using the shipped helper, then qualify it. Cached prepared-image import alone cannot pass this gate. | Integration acceptance remains the largest uncertainty; native recipes are now in public source. |
| 4. Minimum operator controls and removal | Receipt-backed stop/start, live launchd status and first-install deactivation implemented; existing account/empty-home removal retained | Stop/repeated stop/qualified restart and live status passed on the established deployment. Actual first-install deactivation remains to be accepted; it retains images, credentials, accounts and receipts. Destructive purge remains separate. | Stop/start and deactivate the rehearsal installation without affecting unrelated resources or deleting retained images. | Native integration acceptance; no new management framework. |
| 5. Complete release rehearsal and PR closure | Coordinator delegation, release archives and downstream artifact checks already passed on the established deployment | Build one candidate containing the final path; run the documented installation rather than private development scripts; test one interruption/retry, first activation, delegated artifact job, stop/start and removal; reconcile the guide with actual commands. | Signed coordinator result and verified artifact from the candidate installation, plus recorded lifecycle outcomes and retained working baseline. | Testing plus fixes; not a substitute for packages 1–4. |
The original planning allowance for that narrowed path was roughly one to two focused engineering weeks, plus download/CI/operator waiting time. This is a low-confidence source-audit estimate, not a delivery promise. Fresh guest preparation is the largest variable. Review the estimate after the first complete candidate can prepare a guest and activate from absent definitions; do not keep calling each new component rehearsal the final step.
What is already tested, and what is only integration-tested locally
- Native accounts/homes, keychains, pinned dependencies, restricted helper creation, APFS storage/data layout and template import have passed focused administrator rehearsals. They do not need wholesale reimplementation or repetition unchanged.
- The native template worker has now passed its real cached-image batch, including refusal cases and baseline restoration. Its parent preparation journal has unit coverage for checkpoints and replay; the whole fresh preparation transaction has not been run from release artifacts.
- Existing-service replacement and in-flight maintenance are qualified. The new
install-activatepath connects first activation to verified preparation, but still needs the integrated administrator/release rehearsal. Existingservices-activate --stoppedcontinues to mean replacement of saved definitions. definitions::generatedeliberately emits disabled, incomplete review inputs. It is not a runnable adapter configuration generator.- At the audit,
provider_preparation::preparewas library-only. The subsequentinstall-preparecommand exposes that stage (see below); complete first installation through activation remains unfinished. - Native fresh acquisition, seeding and first-boot finishing are now connected to
install-prepare. The earlier private helpers remain historical acceptance evidence, not installation prerequisites. Prepared imports still require reuse; fresh preparation requires a separate explicit create selection. Combined public path acceptance is pending.
Source anchors: CLI, preparation composition, definition preview, service activation, template selection/worker, resource journal.
Execution order and boundaries
- Freeze the narrow input/output contract for packages 1–4. Keep the existing resource APIs and receipts; add only the connections necessary for that flow.
- Implement the missing host activation and fresh vanilla preparation together into one candidate. Use local unit/native unprivileged tests while developing; batch administrator acceptance instead of creating another stream of tiny release builds and isolated sudo rehearsals.
- Build with the current working provider and stage the candidate beside it. Preserve the current runtime, credentials, receipts and cached image. Testing a genuinely unprepared guest requires cached upstream bytes or a separate upstream image; the modified prepared image cannot masquerade as that input. Confirm retained upstream material before proposing another large download.
- Run the integrated operator rehearsal, fix actual failures, then update PR evidence and the guide. Do not retire the baseline before the delegated job and restoration/removal outcomes are known.
Keep these out of the remaining release work: menu-bar UI, automatic update selection, a general repair/migration engine, automatic local pairing, Linux-on-Mac, concurrency controls and additional image variants. Existing implementation stays; new convenience work is deferred. Explicit VPS approval can remain manual and basic management/removal can be documented commands backed by the existing code.
Runtime shutdown/network recovery is a separate operational concern. Existing normal maintenance acceptance does not prove abrupt shutdown or reboot behavior. Document known limits and treat any failure that leaves unsafe job admission, unreported work or inaccessible services in the integrated rehearsal as a blocker; do not use this audit to promise those cases are already solved or to expand into a general lifecycle redesign.
Verify downloaded release inputs
Use an already authenticated setup executable. Before running a newly downloaded executable, authenticate the release publisher and verify its archive using the system's checksum tool. A digest obtained only from the same download server is not publisher authentication.
The native helper can then verify the three macOS provider archives in one read-only step:
sh
./ngit-ci-macos-setup release-verify \
--directory ./downloads --checksums ./downloads/SHA256SUMS \
--sha256 <authenticated-SHA256SUMS-digest> --version <release-version>This command needs neither sudo nor host Nix/Python. It verifies the checksum list's digest first, then streams the adapter/setup, provider and guest-tools archives for the selected version. Coordinator and other-platform archives in the checksum list do not need to be downloaded. Missing archives, changed bytes, duplicate or unsafe filenames, symlink files and oversized inputs are rejected. Success emits JSON containing the authenticated checksum-list digest and each verified filename, digest and byte count. It does not extract or execute archives, inspect images, modify services, or establish publisher trust on its own.
Keep the verified archives and checksum list together for the installation. This is a point-in-time integrity check, not permission to replace their contents: privileged preparation still checks its pinned inputs before use. Archive verification does not qualify the installation, and the remaining input flow and complete fresh-install acceptance below are still required.
Generate the provider installation intent
install-config turns explicit operator choices and authenticated release archives into the input for install-plan, install-preflight, install-prepare and install-activate. It is read-only and needs no sudo, extraction tool, host Nix or developer tools. The initial helper must itself already be authenticated.
sh
./ngit-ci-macos-setup install-config \
--choices ./provider-choices.json \
--directory ./downloads --checksums ./downloads/SHA256SUMS \
--sha256 <authenticated-SHA256SUMS-digest> --version <release-version> \
--acknowledge-dependency-licenses > ./provider-intent.jsonUse the licence acknowledgement only after reviewing the pinned Tart and Softnet licences for your intended use. This flag records that decision; it does not grant a licence. The command verifies all three provider archives, obtains the two host bundle manifest hashes from the authenticated compressed bytes, and derives the guest archive path/hash and the shipped third-party pin/licence hashes. Operators do not copy those internal hashes by hand. It neither downloads third-party inputs nor extracts/executes archive contents. Privileged preparation checks its inputs again before using them.
Start with the editable provider choices example. Replace every angle-bracket placeholder and both absolute archive paths; the example deliberately fails validation unchanged. It selects the reviewed vanilla upstream pin, one 4-vCPU/8-GiB job and a 64-GiB quota. Adjust these budgets to the host and workload before preflight. Resolve the listed Apple hosts from the installation network and review their public IPv4 addresses; these temporary guest-preparation endpoints are separate from the job egress allowlist. Do not copy another operator's addresses, coordinator trust or artifact endpoints.
The choices file is a JSON object with these five fields, using the field definitions in this reference:
| Field | Operator decision |
|---|---|
connections | Relay and Blossom URLs, plus optional provider_blossom_timeout_seconds for slow transfers. |
provider | Approved coordinator hex public keys; vCPUs, RAM, quota and host reserve; max_jobs: 1; one vanilla image with upstream digest and intent: "create". |
storage | APFS container UUID and quota_bytes, matching provider.storage_mib; no existing volume reuse. |
network | Explicit reviewed production restricted-egress or protected-address policy. |
fresh_template | Local absolute Nix and guest-agent archive paths, reviewed Apple endpoint addresses and acquisition/tools deadlines; omit guest_archive, guest_sha256 and cache_home. |
The helper fixes provider-only mode, a new signing identity, new accounts/homes and dedicated storage. It refuses supplied generated fields and does not adopt legacy accounts, credentials, volumes or personal caches. Existing reviewed advanced intents remain usable through the lower-level commands; this fresh-input helper does not rewrite them. The opaque identity_refs.provider value is a local reference, not a secret or a request to import an existing identity.
Check the command's exit status before using the redirected file: failure may leave an empty output file. Then review the generated intent and run:
sh
./ngit-ci-macos-setup install-plan --config ./provider-intent.json
./ngit-ci-macos-setup install-preflight --config ./provider-intent.jsonA valid intent is not proof of installed resources, sufficient current disk space, network isolation or coordinator approval. Keep the same reviewed intent throughout preparation, retry and activation. Fresh-path hardware acceptance remains pending; this command alone does not close the complete installer gate.
Provider resource preparation command
ngit-ci-macos-setup install-prepare --config <intent.json> --adapter-source <extracted-adapter-release> --provider-source <extracted-provider-release> --tart-archive <tart.tar.gz> --softnet-archive <softnet.tar.gz> exposes the existing provider-only preparation transaction. It requires administrator privileges and already authenticated input pins. The project bundle source flags may be omitted when the matching immutable bundles are already staged. Archive paths remain explicit; a completed dependency receipt reuses installed bytes.
The command reads the bounded configuration once, runs the existing admission checks and checkpointed preparation, and returns state: prepared with services_started: false. With fresh_template it acquires the upstream image and prepares the guest; other release inputs must already be authenticated and local. It does not start production services or establish remote approval. This is the preparation stage of the eventual operator flow, not a complete install command. Existing low-level account apply remains an account-only operation.
To add reviewed download endpoints to an existing restricted policy, repeat --add-egress-address <public-IPv4> on services-activate. Existing approvals are retained; the helper rejects private addresses and never converts a protected-address policy. The normal activation transaction drains jobs, qualifies the new policy and retains the prior definitions for rollback. Reusing the current bundle hashes permits a policy-only update. Review each destination; this command does not resolve domains or maintain guest hostname pins.
Minimum provider lifecycle commands
The native helper now exposes these controls for an installation with a service activation receipt. On 2026-10-24, candidate 1930b8e passed native stop, repeated stop, qualified restart and live status against the established runtime. It also correctly refused first-install deactivation of that legacy replacement receipt. Original service definitions and receipt content were preserved, as were images and credentials. Evidence: ngit-ci-installer-controls.70sva8x2. A subsequent read-only check observed both services running and the receipt active. This tests the candidate helper controlling the existing runtime; it does not qualify a fresh installation, actual first-install deactivation or a delegated job executed by the candidate runtime.
The same candidate's adapter and provider bundles were then activated on the established deployment with runtime-stage and services-activate. Explicit drain, adapter qualification and provider startup passed; subsequent live status reported both services running with an active receipt. The prior definitions remain available through services-rollback. This establishes candidate runtime startup with retained configuration, not fresh account provisioning or delegated job success.
sh
ngit-ci-macos-setup services-status --live
sudo ngit-ci-macos-setup services-stop
sudo ngit-ci-macos-setup services-start
# First installations only; deactivates services and retains all data:
sudo ngit-ci-macos-setup install-deactivateservices-status without --live remains the last published checkpoint. The live option adds only current launchd registration, state and PID for the provider and adapter, never command arguments or environment values. A running process is not proof of coordinator connectivity or successful jobs; verify those through CI.
Stop requests the existing explicit provider drain before launchd removal, allowing active jobs to finish. Start accepts a recorded stopped candidate, qualifies the adapter, then admits the provider. Both serialize on the activation lock, require unchanged recorded definitions, and retain the original rollback baseline. No images, accounts or credentials are removed. Start does not silently stop an already active installation.
Interrupted stop leaves stopping; repeat stop. Interrupted start leaves starting; either stop or retry start, which drains the partial start first. If native drain cannot prove safety (including an unavailable maintenance handshake and insufficient legacy launchd grace), it refuses rather than forcing termination; retain the receipt and inspect the failure. Use this helper version or newer for these phases: older recovery helpers cannot parse the new lifecycle checkpoints. services-rollback remains available to restore the retained original baseline.
install-deactivate is restricted to a first-install receipt with an absent baseline; it drains and removes only that installation's two service definitions. It does not mean replacement rollback, which could start an older provider. Accounts, private credentials, images, quota volume, runtime bundles and recovery receipts remain on disk. Purging those resources is outside this command; existing receipt-backed empty-home/account removal remains separate. This gives operators an explicit way to turn off the installation without losing expensive downloads.
Fresh vanilla preparation inputs
The implementation accepts fresh_template instead of template_imports in the non-secret installation configuration. This path currently supports exactly one vanilla image with intent: "create". It uses the already prepared adapter account, keychain, pinned host runtime, restricted Softnet helper and quota volume. Host Nix, Python and developer tools are not invoked by this path.
| Field | Meaning |
|---|---|
guest_archive, guest_sha256 | Absolute local guest-tools release archive path and authenticated SHA-256 (64 hex characters, no prefix). |
nix_archive, rpc_archive | Absolute local pinned Nix installer and Tart guest-agent archive paths; bytes are checked against the shipped pins. |
cache_home | Optional dedicated adapter-owned Tart home on the selected quota volume. Omit or use null to create preparation under the destination Tart home. Never select a personal Tart home. |
apple_endpoints | Explicit reviewed domain-to-public-IPv4 mapping accepted by the guest worker for Apple downloads; separate from the production job network policy. |
download_timeout_seconds | Upstream acquisition deadline, 300–43200 seconds. |
tools_timeout_seconds | Guest tools deadline, 300–43200 seconds; use at least 14400 on slow links. |
The selected image's upstream_sha256 pins the vanilla OCI manifest. Acquisition uses pinned Tart with automatic pruning disabled; an existing manifest-bearing cache is validated and reused without a download. An incomplete cache may require explicit inspection if validation fails. This does not authenticate all mutable cached disk blocks. The portable upstream digest remains in provider offerings; no provider-specific disk hash is added to environment identity.
Root-owned checkpoints under /Library/ngit-ci/fresh-templates bind the inputs, source home, runtime bundle and upstream pin. The helper records its unique clone name before creation, seeds authenticated payloads, runs the native preparation session, finishes only the receipt-owned adapter setup session, then imports the qualified template through the existing receipt-backed worker. Session cleanup accepts only the same signed Apple helper executables as runtime maintenance; VMs or other processes still block completion. Nix installation runs inside the guest. The tools stage may download CLT; sealing is followed by a distinct offline cold boot and build qualification.
A completed retry verifies the recorded selection and imported files without acquiring, seeding or booting again. An incomplete read-only verification fails. A failed download before a clone exists can retry; an existing destination after an interrupted clone is preserved and requires explicit recovery. An interrupted attachment is also preserved with its evidence instead of blindly mounting again. After recorded seeding, retry uses the native session's resume checks. Do not change the installation configuration or delete its receipts to bypass a failure. The acquired cache and preparation clone are retained; this stage does not reclaim them or activate production services.
This integration passes local setup tests and native compilation; it is not yet qualified as a complete fresh installation from release artifacts. The accepted native continuation/finish batch above does not establish fresh first-install or public acquisition/checkpoint acceptance.
The activation state machine also supports a schema-2 receipt with an explicitly absent baseline. A failed first installation can remove its own partially published pair after drain without attempting to start a nonexistent prior pair. Existing schema-1 replacement receipts still require both baseline definitions. This is first-activation recovery support; the command below uses it without treating an existing pair as a fresh installation.
The initial provider candidate renderer requires an explicit network object in the installation intent. Select either {"mode":"restricted","addresses":[...]} for a reviewed public IPv4 allowlist, or {"mode":"protected","addresses":[...]} for the complete host/management IPv4 inventory to block. Neither mode has an implicit address list or unrestricted fallback. The adapter repeats network validation and qualification at startup; configuration validation alone does not prove isolation.
This renderer binds one vanilla offering to its upstream digest, derives the provider state/work and Tart paths from prepared-resource bindings, and keeps the signing credential in the provider's private configuration rather than a plist. It emits enabled candidate dictionaries for the activation transaction, but does not publish them, create supporting directories or start services. Bindings must come from verified receipts before native activation; arbitrary path inputs are not resource ownership evidence.
ngit-ci-macos-setup install-activate --config <same-intent.json> connects this candidate to first activation. Both service definitions and registrations must be absent. Under installation, account and service-operation locks it verifies every completed preparation checkpoint against the unchanged intent, then resolves the storage and dependency paths from their resource receipts. Incomplete or changed preparation must be corrected explicitly; activation does not silently apply steps.
It provisions a separately recorded adapter-owned, execution-group-readable socket directory, refusing an unrecorded existing directory. Service logs are mode 0600 in each private service home. The adapter must qualify before the provider starts. On interrupted activation, use services-rollback before retry: rollback drains the pair and removes only its recorded definitions, retaining prepared resources, images, logs and credentials. Retry after rollback must select the same candidate. This initial path has code/test coverage but has not yet passed the complete administrator release-installation rehearsal; it does not prepare an upstream guest.
Provider storage preparation
Native provider preparation requires an explicit storage selection containing container_uuid, quota_bytes and optional reuse_volume_uuid. The quota must match provider.storage_mib; reuse also requires storage in the reuse list. The installer resolves device identifiers from APFS metadata on each operation; it does not persist device numbers that can change after a reboot.
The protected /Library/ngit-ci/storage-preparation journal reserves a random NGITCI-<UUID> label before creation and then binds the resulting volume UUID. Retries recover that exact label and refuse duplicate or mismatched volumes. An existing dedicated NGITCI or NGITCI-<UUID> volume can instead be selected by UUID. Reuse checks metadata only: it never changes ownership, resizes, erases or adopts the volume. Ownership must already be enabled for reuse. New volumes have ownership enabled before the storage checkpoint completes. Their root directory must be root-owned; preparation removes group/other write permission from that newly created volume root. macOS may initially create it as root:admin mode 0775. Reuse and later status checks refuse writable volume roots without repairing them.
Both paths enforce the adapter's remaining-quota and host-reserve checks below. The storage checkpoint hashes stable volume metadata, not disk-image contents; free and used space are checked again without becoming part of the checkpoint. Volume UUIDs are local installation evidence, not portable environment identity. The separate receipt is retained with storage; this component provides no volume deletion operation.
Provider preparation journal schema 4 includes storage and prepared-template checkpoints. Older preparation journals require explicit migration; changing only their schema number is rejected. This is not yet a complete storage/template installer: fresh guest preparation, qualification and activation remain separate integration work. Native compilation and parser checks alone do not establish APFS creation acceptance; the completed storage/layout rehearsal is recorded below.
Native storage/layout acceptance passed on macOS on 2026-10-23 at 4c8bb62. The initial run created and recovered the test volume, then correctly refused its root:admin mode-0775 root. The corrected recovery revalidated the retained receipt and exact volume UUID, secured that created root, passed reuse and private-directory publication/retry checks, and removed the exact disposable volume. Production adapter/provider PIDs were unchanged. This establishes the storage/layout component, not full fresh installation or template preparation.
Private data directories
The storage step also prepares ngit-ci-provider and ngit-ci-tart directories on the verified volume. Their ownership records live separately under /Library/ngit-ci/storage-layout/<volume-UUID>; they never replace account login homes or the home receipt. Creation uses the same staged publication and inode/device checks as service homes. An existing unrecorded destination is refused rather than adopted, including when the containing volume is reused. Cached images elsewhere on that volume are untouched.
Provider configuration selects state and work beneath the verified provider data directory. The provider creates those children as its own account. The adapter directory is reserved for template integration; this preparation step does not launch Tart or select a live template. Retries verify both data-directory identities and the original account records. Running services or account processes block preparation. Removal remains empty-only; retained job data or images cannot be recursively deleted through the directory helper.
Combined native storage acceptance
The ignored library test provider_data::tests::native_storage_and_layout_batch requires an explicitly selected APFS container in NGIT_CI_STORAGE_TEST_CONTAINER and interactive administrator authorization. It creates a new 8 GiB quota, writes only small test metadata, exercises recovery after volume creation and repeated external reuse, then publishes and removes empty private data directories. It deletes only the exact test-created volume after rechecking its receipt, UUID and reserved label. Existing CI volumes, VM images and production services are not selected by this test.
The protected recovery receipt is retained under /private/var/tmp/ngit-ci-storage-batch.*, including on failure. The test uses synthetic account records in memory; it creates no macOS accounts. It does not qualify template preparation, fresh service activation or the full installer. Run only this exact ignored test from a verified executable, not the entire test suite as root. Group this acceptance with other required administrator checks; it does not require another delegated release build.
Prepared-template import component
template_import copies a reviewed, stopped standalone template on the same APFS volume using fclonefileat. There is no streaming-copy fallback, network request or whole-image hash. The caller must hold the source and destination lifecycle leases, validate fixed ancestors and retain the expected source metadata and provenance in its protected preparation record. Prepared imports are connected to the resource preparation transaction below; the guided installer and fresh guest preparation remain unfinished.
The importer checks the three owned regular files (config.json, disk.img, nvram.bin), rejects links, shared writes, suspended state and stacked/ASIF layouts, and reads only the bounded configuration file. It stages private clones, checks the source again, records source/installed file identities, then publishes without replacing an existing directory. Matching retries verify the existing copy; changed inputs or destinations are refused. A crash can leave a private staging directory, which a retry does not adopt or delete.
The import receipt retains the explicit upstream OCI pin and an optional reviewed preparation-recipe digest. Legacy imports without a complete recipe record use no preparation digest rather than inventing one. These declarations do not authenticate the original image. Inodes and modification times are local change guards, never portable environment hashes. Imported templates still require adapter qualification before admission; successful copying is not guest readiness.
Portable interruption/refusal tests and native tiny-fixture APFS cloning passed. The native test verifies that changing the clone leaves its source intact. The separate fixed-source rehearsal drains the live pair, takes its lifecycle lock, imports/retries/verifies the cached template, removes only the test copy, and restores the same qualified runtime. This real-image acceptance passed on 2026-10-23 using importer a2b0109: APFS import, stable retry, verification and exact-copy cleanup succeeded, the source remained unchanged, and the original qualified services resumed with their definitions and receipt unchanged. The first attempt exposed omitted Apple session helpers in the maintenance guard; b24a4cf fixes that guard. This acceptance does not establish a fresh installation or qualification of a newly prepared guest.
Prepared-template journal integration
Native provider preparation now requires template_imports covering every selected image with explicit reuse intent. Each selection supplies the family, dedicated source Tart home and template name, expected source metadata, upstream OCI pin and optional reviewed preparation-recipe digest. The wizard will produce these records; operators should not have to transcribe file identities. Missing imports, changed upstream pins, duplicate families and path traversal are refused. Fresh image creation is not silently treated as reuse.
After storage, dependencies, configuration and keychain preparation, the journal checkpoints template intent before invoking a bounded worker as the dedicated adapter account. The parent verifies account and storage receipts, stopped services and the selected immutable setup executable, then clears supplementary groups before dropping identity. The worker imports only within the selected mounted quota volume, into its receipt-owned ngit-ci-tart/vms directory. Source and destination lifecycle locks prevent concurrent use. A source on another volume fails without streaming a full copy.
Retries verify published imports against the saved selection; a completed import can be verified without reading the original source. The preparation journal binds the resulting local file evidence, so changed installed copies are refused on later verification. Local metadata belongs only to the installation journal; portable environment identity continues to use the upstream image and reviewed configuration. No disk-image hashing, service activation, download or guest boot is performed by this step. The native worker acceptance passed on 2026-10-23 at 00abd8d, including apply/retry/verify and changed-pin, wrong-destination and empty-selection refusal, exact-copy cleanup and restoration of the original services. This does not qualify the whole parent preparation transaction or a full fresh install.
Provider dependency reuse inspection
provider_dependencies verifies explicitly selected existing runtime files before reuse. The checked-in Tart 2.41.1 / Softnet 0.24.1 pins were derived from the previously pinned upstream release archives, after rechecking each archive's SHA256. They cover every file in tart.app, the Softnet executable, and the archive/license digests. They do not include VM images. A caller must obtain these pins through a trusted release; a self-supplied checksum is not publisher authentication.
The inspector checks the exact Tart app tree, file hashes, ownership and modes, and refuses extra entries, symlinks, hardlinks and writable directories. Softnet must already have mode 4750 and the selected non-root network GID. Native inspection selects only /Library/ngit-ci/runtime/tart-<version>/tart.app and softnet-<version>/softnet, validates root-owned ancestors, resolves the dedicated ngit-ci-network group and runs the system code-signature verifier on Tart. It never executes Tart/Softnet, searches personal paths, grants permissions, changes receipts or adopts resources.
This is an integrity/permission prerequisite, not complete dependency setup. Acquisition, license presentation/acceptance, license retention in owned copies, network-group membership policy, signed-release authentication and atomic installation/removal remain separate work. The native rehearsal is read-only; passing it does not claim fresh dependency installation or network isolation.
Pinned archive preparation
dependency_archives prepares cached Tart/Softnet .tar.gz files without a shell extractor or execution of downloaded code. Pins must come from an authenticated release; this component does not establish publisher identity or fetch archives. Each source is copied to a private temporary file and its full compressed SHA256 verified before parsing. Archive size is bounded to 256 MiB per input and expansion to 512 MiB per archive, with at most 4096 entries.
Only the pinned application/helper files and licenses are materialized. Paths must be relative normal components; links, special files and duplicate entries are refused. Archive permissions, owners and extended attributes are not applied. Every extracted selected file is hashed again; executables become 0755 and licenses/data 0644 under a private 0700 temporary root. Gzip trailer validation and missing-file checks must also pass. Failure removes only that attempt's private source tree; original cached archives remain intact.
Run this before the administrator phase, then pass its two source directories to provider preparation. The root-owned bundle stage independently copies and re-verifies these mutable sources before publication. Source trees normally expire with their handle; retaining one for a later administrator run is explicit. Network acquisition, resume/download UI and license presentation remain separate.
Inactive dependency bundle staging
dependency_bundle copies selected, already-extracted Tart/Softnet release files into /Library/ngit-ci/dependency-bundles/<pins-digest>. The digest covers the canonical pin manifest, not a VM image. Both upstream license files are retained and checked. The caller must authenticate the pins and handle license acceptance and archive acquisition/extraction before staging.
Copying opens every relative source component without following symlinks and checks hashes on the new private copies. An operation lock excludes concurrent installers. Only a fully verified bundle is published, using exclusive rename; existing bundles are re-verified without replacement, even if original sources are no longer present. Interrupted publication can leave an unreferenced private stage directory; a retry does not delete stages from another attempt. Published files are rechecked on every reuse, including licenses and the manifest.
Softnet is staged with mode 0755, without setuid or network-group privileges. Staging changes no live runtime paths, service definitions or selected versions. The source-only native rehearsal verifies Tart's signature on the staged app and repeats staging while checking directory identity. This is an inactive copy, not an activated dependency installation: receipt-bound helper permissions, selection, rollback/removal and integration into provider setup remain required.
Restricted network helper preparation
network_helper prepares a separate copy at /Library/ngit-ci/network-helpers/<dependency-pins-digest>/softnet. It reads only an already verified inactive dependency bundle. The copied helper becomes root-owned mode 4750 for the existing ngit-ci-network GID; the immutable source stays mode 0755. Nothing selects this copy for the running adapter.
Before granting permissions, the helper verifies the dedicated group and adapter UID/GID/UUID identities. The group must contain exactly the adapter's name and UUID, without nested groups, duplicate numeric identities or primary-group users. The root-only receipt binds those identities to the dependency bundle and helper hash. Account/group records are references, not adopted resources, and membership is never changed. Native preparation holds the account operation lock as well as its own helper lock, then rechecks the binding before privilege and publication.
A fully prepared private copy is published without replacement. Repeated apply verifies the existing receipt, bytes and permissions. Changed group identity, membership, receipt or permissions fails without overwriting the existing copy. This prepares a restricted helper; it neither executes it nor changes sudo policy, service definitions or the live helper. Transactional selection, removal and provider-installation integration remain separate work.
Composed dependency preparation
dependency_preparation joins inactive bundle staging and restricted helper preparation into one resumable transaction. The selection binds the authenticated pin manifest and both license hashes to an explicit acknowledgment. It records intent, verified bundle, bound helper and prepared state in a root-only journal at /Library/ngit-ci/dependency-preparation. The account operation lock protects identity checks while component locks protect publication. A retry re-verifies completed resources and refuses changed intent or helper identity; it can reuse complete bundles after original download sources have been removed.
The returned Tart/helper paths are prepared references, not active service configuration. Status re-verifies those paths without repairing them. Its local evidence digest includes account identities and must never be used as the portable environment fingerprint. Acquisition, operator license presentation, activation and removal remain separate work. The provider preparation journal now includes this transaction after account/home setup.
The source-only batch rehearsal uses a distinct journal at /Library/ngit-ci/dependency-preparation-rehearsal. Its synthetic selection tests acknowledgment handling without recording production license acceptance. One administrator run checks composition, retries, checkpoint recovery and refusal cases; see testing.
Provider preparation journal component
The setup library has a versioned, configuration-bound preparation journal for runtime, account, home, dependencies, private configuration, keychain and disabled-definition steps. Journal schema 2 requires the dependency checkpoint; schema 1 receipts are preserved and refused pending explicit migration. It checkpoints intent before applying each step and verifies saved resource evidence on retry. Changed input or evidence requires explicit review; completed progress cannot be discarded. Before recording the final completed checkpoint, the controller re-verifies all earlier resources so a later step cannot silently invalidate them. A failure leaves the final step pending. Resource-specific receipts retain ownership authority. The fingerprint covers validated JSON configuration, never locally generated image bytes or signing credentials.
Native provider preparation requires a dependencies object in the JSON intent: schema: 1, pins_sha256, tart_license_sha256, softnet_license_sha256 and licenses_acknowledged: true. Digests must match the release-pinned dependency manifest and its retained licenses. Missing acknowledgment is refused before opening resource stores. Planning may omit this selection; provisioning cannot. Already extracted sources are supplied by the caller and are only needed when the selected bundle is absent. Acquisition and operator-facing license presentation remain prerequisites. No paths from this step are selected for live services, and its receipt does not authorize account or dependency removal.
The preparation backend dispatches runtime, account and home steps through their concrete helpers, keeping the account ownership receipt separate from the progress journal. Both must be reloaded after failure, and callers must hold both operation locks. Preflight refuses registered services before any step. After validating intent and ownership, recovery may finish a recorded keychain operation and its receipt-owned setup session; all account processes must then be stopped before provisioning continues. The configuration step uses a native worker in the selected immutable setup bundle. The parent verifies the stopped accounts and receipt-bound home, then drops to the provider UID/GID with supplementary groups cleared. Only non-secret settings travel over bounded standard input; only a verification digest returns. The worker accepts no credential or home path on argv and never runs as root. Matching retries preserve the settings file and key. The keychain step invokes initialization and verification in the selected bundle's bounded launchd security session, then removes only the receipt-owned setup session. Its local checkpoint uses file identities and credential metadata, never secret bytes or mutable keychain contents. External adapter accounts/homes are deliberately refused by this composition; adopting an existing installation needs a separate migration. Disabled service definitions are checkpointed without registering services.
Provider runtime preparation stages exactly the selected provider/adapter bundles and verifies that their manifests include the required role executables. Retries recheck installed file hashes and preserve immutable versions; a shared bundle may serve both roles. This checks integrity and role coverage, not release authentication, which remains a caller prerequisite. No service is activated.
Private configuration verification is read-only and refuses missing or unsafe files. Its local checkpoint binds expected settings, public signing identity and home identity without hashing secret bytes; this is separate from the portable environment configuration fingerprint. It does not grant ownership or readiness.
Provider account/home step bindings now call the existing provisioning helpers and verify their resource-specific evidence. The account digest covers account records only, so adding home records does not invalidate an earlier account checkpoint. Home evidence includes verified account identity and directory metadata. Provisioning refuses registered services or account processes, and existing accounts/homes require their specific reuse choices; shared execution group reuse requires both account choices. Read-only evidence verification can inspect active services without granting ownership or mutation authority.
The native store uses /Library/ngit-ci/provider-installation, root-owned mode 0700, an exclusive operation lock and atomic mode-0600 journal writes. The separate rehearsal store cannot become a production receipt. There is no operator-facing install command yet. provider_preparation::prepare composes the native resource helpers under both protected operation locks and rejects live services before opening resource stores. Its caller must authenticate release sources; it does not acquire dependencies, provision storage/templates, configure network policy or enroll coordinator trust. Even a completed preparation journal does not authorize activation; dependency, remote approval and canary checks remain separate. See journal tests for fault coverage and the strictly limited native persistence rehearsal.
Native private provider configuration component
The setup library now derives provider-only settings from validated installation input with required relay/artifact endpoints. It can atomically create a mode-0600 .env in an owned mode-0700 home as the service UID, generating a fresh signing key and reporting only its public key. Matching retries preserve the identity and file; changed configuration, links, unsafe permissions and partial files are refused. No key is accepted through installation input or written to a public receipt. This replaces the identity/configuration mechanism of the private Python bootstrap, but is not yet connected to the full installation transaction.
There is deliberately no operator command accepting an arbitrary home path. The composed installer must enforce receipt ownership and stopped-service checks, complete quota-backed paths and adapter configuration, and retain explicit remote approval. Matching contents do not establish ownership. The component always reports activation as blocked. See the native configuration tests for the disposable rehearsal and current validation boundary.
Receipt-backed account provisioning
The Tart release archive also contains ngit-ci-macos-setup, an engineering component for account records and private service homes, not the finished installer. Its native macOS backend uses fixed system dscl, dseditgroup, plutil, launchctl and ps commands without a shell or GUI. It requires no host Nix, Python or CLT. plan --role provider|coordinator|both is read-only; apply with the same flags requires interactive administrator authorization. status reads the non-secret receipt without sudo. --reuse-existing explicitly permits compatible existing identities; they remain externally owned and are never removed by this component. Unexpected homes, identifiers, membership, account properties or administrator membership stop provisioning instead of being silently repaired.
Provider accounts are ngit-ci-adapter and ngit-ci-provider, with the execution and network groups already used by the adapter. The coordinator has its own ngit-ci-coordinator account and group. New numeric identifiers are selected from unused values in 450–499. Users have a disabled password, /usr/bin/false shell, hidden login entry and the fixed service home recorded in the receipt. This account operation does not create those homes, prepare keychains, grant Softnet access, install binaries, pair identities, create volumes, or start services. Those resources need their own ownership and lifecycle operations in the installer.
/Library/ngit-ci/accounts/receipt.json is root-owned and contains only metadata. New receipt directories are explicitly readable/traversable regardless of the administrator's umask; existing directory permissions are preserved. A pre-existing restricted ancestor can still require administrator access to read status. An exclusive operation lock serializes changes, and atomic receipt replacement persists intent before each create/delete boundary. Each record is identified by its Directory Services UUID as well as its numeric ID and expected properties. A retry resumes partially configured records only when that identity matches. Completed records are verified rather than rewritten. Unknown receipt versions, symlinks, shared files, writable receipt paths, changed identities and reused numeric IDs are rejected. An interrupted removal retains enough state to retry without deleting a later account which reused the name.
remove --role provider|coordinator|both requires administrator authorization and removes only receipt-owned account/group records. It preflights all selected records before deleting any, removes users before their groups, and preserves other roles and externally owned records. Registered role services, live account processes, existing homes, changed membership or unrelated users of a primary group block removal. A future installer must drain services and transfer retained data ownership first; this component never recursively deletes data or guesses that an existing directory is safe to remove. Account role changes and reprovisioning a removed production receipt require a reviewed migration; they are not silently inferred by apply. The current component assumes no concurrent external administrator is editing these same Directory Services records.
rehearse is a bounded-operation qualification entry point: it creates a fresh coordinator account/group, applies twice, removes twice, and retains a separate receipt under /Library/ngit-ci/accounts-rehearsal/. It refuses an existing coordinator identity, home or registered service unless resuming its own partial receipt. It starts no service and does not touch the provider accounts. Run it only with explicit administrator authorization and an outer deadline; a failed rehearsal retains its receipt for retry. Unit tests cover interruption after every mutation, receipt-write failure, identifier reuse, partial-role removal and preservation of externally owned resources. Native account creation/removal must also pass before calling this component qualified on a particular macOS version.
On 2026-10-22 the native coordinator-account rehearsal at 826903b passed: fresh account/group creation, two applies, two removals, both identities absent afterward, and existing adapter/provider PIDs unchanged. This qualifies account records only. The rehearsal exposed a restrictive-umask issue with newly created receipt-directory traversal; the follow-up explicitly sets their intended mode and tests it in an isolated process. The existing restricted rehearsal directory is preserved. Fresh home/keychain creation, service installation and complete removal remain separate acceptance gates.
Receipt-backed service homes
After account setup, homes-apply --role provider|coordinator|both creates the fixed private service homes. Administrator authorization is required; selected role services must be unregistered and account processes stopped. Account UUIDs and properties are verified again. Existing homes require --reuse-existing, matching ownership and mode 0700; they remain external and are never removed. There is no recursive chown, permission repair or scan of existing home contents.
Home operations upgrade the account receipt to schema 2 (older schema-1 account receipts remain readable; older tools that only support schema 1 must not be used after this upgrade). Each home has separate ownership, account UUID, operation token, device/inode identity and lifecycle state. Durable intent comes before an empty, root-owned staging directory under the receipt directory. The staging inode is recorded before assigning its service owner and publishing it with an exclusive rename; a destination that appears is never overwritten. Staging and service homes must share a filesystem. Interrupted setup can resume at the staging or final path only with the recorded identity. Recovery of the mkdir-to-checkpoint interval accepts only the intended root-owned, private, empty staging directory. As with account operations, no external administrator may concurrently edit these paths. The root-owned /private/var/lib parent must already exist; this component does not take ownership of shared ancestors.
homes-remove --role ... removes only receipt-owned, empty homes. It never recursively deletes files: data, logs, keychains or unexpected directory identity stop removal and retain the receipt. Transfer or archive retained data explicitly before finishing removal. Owned homes must reach Removed before account removal is allowed; other roles and external homes remain unchanged. Role migrations, reprovisioning removed homes and automated data ownership transfer are not yet implemented. These operations do not install or start services.
rehearse --homes extends the isolated coordinator-account rehearsal to create its private home, apply twice, remove the empty home twice, then remove the account/group twice. It uses the separate rehearsal receipt, starts no service, and refuses to adopt existing homes. The extended native rehearsal at b836004 passed on 2026-10-22: fresh account, group and private home creation, repeated apply and repeated empty removal. The final schema-2 receipt recorded all three resources Removed; independent Directory Services and filesystem metadata checks confirmed their absence. The existing adapter/provider PIDs stayed unchanged. This qualifies private-home setup and empty cleanup, not fresh keychain/service installation or automatic handling of retained data.
For a bounded external qualification, rehearse --homes --prepare-only retains the ready, owned coordinator account/home and its rehearsal receipt instead of removing them. It starts no service. After the external test stops and its own test data is explicitly cleared, run rehearse --homes to perform the normal empty-home/account cleanup. It cannot remove nonempty data, adopt an existing unowned identity, or prepare a receipt whose removal has begun. This is an engineering fixture operation, not coordinator installation.
Native service keychain helper
The Tart release archive includes ngit-ci-macos-keychain. Run it without arguments as ngit-ci-adapter, in the same launchd security session that will start Tart. It unlocks only /var/lib/ngit-ci-tart/Library/Keychains/login.keychain-db using the dedicated virtualization-keychain.password file in that service home. It never takes secret values on argv or environment, disables interactive prompts, and rejects root, another account, symlinked service directories/files, shared files and group/other access to credentials. The home must be mode 0700. Its owned Library/Keychains descendants may have read/search bits (macOS creates these), but never group/other write access; symlinks are refused and existing modes are preserved. Files must be private to the service account. Password format is the existing 64-character lowercase hex credential, not the operator's login password. Credential buffers are zeroed on drop; errors report operation/status without password contents.
This helper requires only system frameworks and the system security utility, not Python or Command Line Tools. unlock is an explicit spelling of its default operation. initialize is the setup operation, also run unprivileged as the dedicated account inside its launchd security session, after the installer has created its private home and account. It creates missing private Library/Keychains directories, generates a random service password, persists it before creating the keychain, unlocks it, sets this account's default keychain and checks automatic login-keychain discovery. It disables framework interaction before accessing a keychain and supplies the password directly with prompting disabled. Discovery is a read-only system command with a 30-second deadline, no stdin and a fixed service HOME. No operator password, personal keychain or graphical approval is part of this operation. A macOS authorization error fails setup; it must not be worked around by enabling interactive prompts.
Initialization takes an exclusive service-local lock. Repeating it preserves the credential and keychain. A failure after saving a complete password can be retried with that same password. An incomplete credential, a keychain without its credential, an unexpected account home, or unsafe existing paths require explicit recovery; setup does not delete, rotate, adopt or relax permissions to hide the problem. Both the credential and any partly created keychain remain after errors. It does not start a VM or any provider service.
ngit-ci-macos-keychain rehearse qualifies fresh creation in the fixed ngit-ci-coordinator account and /var/lib/ngit-ci-coordinator home. It requires a fresh private home with no credential or login keychain, uses the same framework implementation as production, initializes twice and unlocks again, and verifies credential metadata is unchanged on retry. It accepts no account, path or password arguments. The normal initialize/unlock commands still select only the adapter account/home. Run the qualification in a disposable launchd security session after preparing the owned fixture; it leaves its generated data for the test controller to clean up. This command neither removes keychains nor accesses the production adapter home. The test controller checks that the home is empty before starting launchd. The helper checks for absent credential/keychain files afterward, because session startup can create unrelated service metadata before the helper runs. It still validates directory ownership and permissions and refuses existing or linked credential/keychain paths.
Fresh native keychain creation, repeated initialization and unlock passed in the isolated launchd session at a1bcec1, with credential metadata preserved and interactive prompts disabled. Cleanup also passed after removing the disposable account's launchd user domain: the fully validated fixture contained 57 entries, 1,615,478 bytes and 14 directory levels. The controller removed its test data, then the native setup component removed the empty home and owned account/group. Independent Directory Services and filesystem checks confirmed their absence; production provider/adapter PIDs remained unchanged. This does not establish Tart HostKey creation in the new account or production service installation.
Account/home lifecycle and fresh keychain initialization now have native acceptance evidence. Installed runtime ownership, the native service launcher, and complete installation/removal remain separate work. Keep the working service launcher until its replacement passes native testing. A different SSH security session alone is not launchd qualification.
Versioned runtime staging component
ngit-ci-macos-setup runtime-stage --source <extracted-archive> --sha256 <manifest-sha256> stages one verified release archive under /Library/ngit-ci/runtime-bundles/<manifest-sha256>. Administrator authorization is needed only for staging. runtime-status --sha256 <manifest-sha256> verifies its installed contents and prints the non-secret manifest without sudo.
First verify the release archive against the trusted release publication, then compute the SHA256 of its manifest.json. The supplied digest pins exact bytes; it is not a signature or proof of publisher identity. Darwin release archives include a schema-1 manifest with a files map of fixed executable names and LICENSE to lowercase SHA256 digests. Extra names, path traversal and unsupported schemas are rejected. Staging reads only listed files and never executes them. Tart/Softnet bundles and their separate notices are outside this component.
The installer copies to a private directory, verifies the copied bytes, writes the manifest, syncs, and publishes with an exclusive atomic rename. Published executables are root-owned mode 0755, the manifest/licence mode 0644. An existing version must pass complete content, ownership, mode and entry-count verification; it is never overwritten or repaired. A lock excludes concurrent installers. File size is bounded at 256 MiB; manifests at 16 KiB. Normal errors remove only the new temporary staging directory. A hard process/machine interruption may leave an unreferenced .stage-* directory; retry can publish a fresh candidate, but cleanup of such leftovers needs a later ownership-aware maintenance step.
Native staging acceptance at 023eae1 passed with a small setup/licence bundle: initial staging, repeated staging preserving the directory identity, and manifest verification completed with production adapter/provider PIDs unchanged. A separate ordinary-user SSH invocation of the installed runtime-status also passed. The candidate remains installed but inactive. This does not qualify complete release-archive production or service activation at this revision.
Staging itself changes no current-version link, account or service. The separate activation commands below switch the existing provider service pair; runtime removal is not implemented. Staging preserves runtime versions, images and services. Activation verifies the required role bundles and retains the previous service definitions; staged content alone is not readiness evidence.
Native provider activation and rollback component
The setup executable now provides a transition for an existing configureddev.ngit.ci.adapter / dev.ngit.ci.provider pair. It does not create initial service definitions, install coordinator services, configure Tart/Softnet or migrate provider state. Keep the existing configuration and a compatible working runtime available.
Native activation and rollback passed on Apple Silicon with setup revision 332d014, previously qualified adapter/provider binaries from 79c8cc4, and native keychain helper a1bcec1. Both candidate and restored adapters qualified before their providers started. The rehearsal verified that original service definitions and provider configuration were restored byte-for-byte and both services were running. An independent ordinary-user services-status check reported restored. This validates the existing-service transition; it does not establish a clean installation or delegated CI acceptance of the latest revision.
Run the installed setup executable from a root-owned, service-traversable runtime bundle. Administrator commands require interactive authorization:
text
ngit-ci-macos-setup services-activate --adapter-bundle <manifest-sha256> --provider-bundle <manifest-sha256>
ngit-ci-macos-setup services-rollback
ngit-ci-macos-setup services-statusThe adapter bundle must contain the adapter, native keychain helper and setup executable; the provider bundle must contain the unwrapped provider executable. Both staged manifests and all their files are verified. Baseline services must be registered, the adapter qualified, and their root-owned definitions must use the dedicated accounts, execution group, SessionCreate and supported shutdown policy. The legacy bounded maintenance controller must be closed first.
Activation saves both original and candidate plist bytes in a root-only receipt under /Library/ngit-ci/service-activation before stopping anything. It drains the provider before the adapter, refuses leftover workloads/control sockets, replaces definitions atomically, and starts the adapter first. A separate probe runs as the provider account, checks the Unix socket peer identity and requires a hardware-VM aarch64-darwin description before provider startup. Observed provider process startup is not proof of a delegated job or advertisement delivery.
The new launch-adapter --sha256 <manifest-sha256> entrypoint accepts only the adapter account, verifies its private home and staged bundle, unlocks its keychain in the existing launchd session, then execs system caffeinate -is with the adapter. It preserves the service environment and uses a system-only PATH; no Python, shell, compiler or host Nix is needed by this launch path. Existing service configuration, images, signing credentials and job history are retained.
Failures during drain, replacement or startup attempt to restore the saved baseline when drain and readiness checks permit. A checkpoint-write failure or interruption retains the last durable recovery information; run services-rollback to resume. It also explicitly rolls back a successful activation. Definition changes outside the transaction cause a refusal instead of an overwrite. Successful subsequent activation retains the immediately previous service definitions; this is runtime replacement, not a state-schema migration. Do not use it across incompatible state/configuration versions.
Before asking launchd to stop a current provider, setup requests an explicit provider drain and waits for drained. The provider finishes admitted jobs and bounded publication, then stays alive with admission closed until service stop. Setup then removes the provider and adapter in order. Failed/lost acknowledgements or an exceeded wait deadline do not authorize forced termination. See the provider drain contract for result delivery semantics. Activation enables the maintenance option in the candidate provider plist and requires a binary advertising support for it.
Older providers without this handshake must still have an effective launchd exit timeout of at least one hour on both services. A plist requesting ExitTimeOut is not sufficient: the qualification Mac reported 60 seconds and interrupted a job during the earlier rehearsal. Such legacy services need a separately verified idle migration. After both services have been removed and all workloads stopped, services-activate --stopped accepts their retained definitions and performs the same receipt-backed replacement/readiness sequence. It refuses registered services or remaining workloads and does not drain them on the operator’s behalf. Do not bypass the guard while jobs may be running.
Native in-flight qualification passed on 2026-10-22 with provider c3664ac and setup e5e5f82: a delegated macOS release build completed successfully during a drain lasting about 5 minutes 47 seconds. Results were delivered before service removal; the adapter requalified and the provider resumed with one available slot. The dependent Linux job verified all three Darwin archive checksums and contents. This qualifies same-bundle maintenance of the existing deployment, not a clean installation or every rollback/failure scenario.
Keep the administrator terminal open. Each system command and readiness wait is bounded: provider shutdown can wait up to its one-hour grace, adapter shutdown up to four minutes, and adapter qualification up to thirty minutes. These are ceilings, not expected startup durations. There is no background recovery watchdog; a killed process or machine interruption requires an explicit rollback command. The private receipt can contain service environment values and is never printed. services-status needs no sudo and prints only the last published phase; this checkpoint can lag an interrupted receipt write and is not a live health check.
Hardware appointment and installation
Record the Apple chip, macOS version, RAM, free APFS space, home/dedicated use and desired Xcode version. The proposed pinned runtime pair is Tart 2.41.1 and Softnet 0.24.1; the latter requires macOS 26 or newer on the host, even though Tart itself supports older hosts. Runtime preflight requires the exact 2.41.1 / softnet 0.24.1-6e8b5ff version responses; a response checks compatibility, not provenance, so installation must still verify the pinned binaries. Do not silently install an older Softnet or fall back to default NAT to accommodate an older home Mac. Start with one slot and an 8-GiB guest plus at least 4 GiB additional host headroom: planning estimates to measure, not proven performance guarantees. Disk admission uses a dedicated quota-limited APFS volume for the template and its copy-on-write job clones; see the storage setup below. Virtual guest disk capacity is not a host free-space requirement.
Initial setup needs interactive administrator access for pinned virtualization and network components, macOS/Xcode terms and guest first-launch setup. Use the operator's existing SSH agent if remote access is chosen; never copy a private key into the service or guest. On a home Mac, schedule network tests while the operator can recover connectivity. Do not run services as the personal user.
Before enabling automation, the installer must provide:
- Verified, pinned Tart and Softnet binaries with recorded licenses/versions.
- A private mode-0700 adapter home and separate provider-owned credential state.
- launchd services with explicit environment, restart policy and private logs; an adapter socket accessible only to the provider account.
- Host-enforced denial of private, link-local, metadata and management access, including the host's public addresses. Default NAT is insufficient.
- Fail-closed checks for virtualization, template/runtime drift, network policy, resource reserves and cleanup of interrupted jobs before admission.
The host-inspection library checks native Apple Silicon, Hypervisor support, macOS 26+, APFS and static capacity (at least one logical CPU and 4 GiB RAM left for the host). It uses Apple’s documented Hypervisor capability check and physical-memory query. This is capacity planning, not a memory reservation against personal applications, and still needs real-host validation.
These pieces are still implementation gates. Do not replace them with an unrestricted tart run. Home sleep, logout and Wi-Fi/VPN changes must withdraw capacity or be demonstrated safe; dedicated hosts need reboot recovery too.
Adapter entrypoint (qualification only)
For native source validation, nix develop .#macos-provider supplies the same pinned Rust toolchain and library dependencies as the packages without pulling in act or the coordinator's Grasp integration harness. On Apple Silicon, run:
bash
nix develop .#macos-provider --command cargo check --locked -p ngit-ci-nix-provider -p ngit-ci-adapter-microvm --all-targets
nix develop .#macos-provider --command cargo test --locked -p ngit-ci-adapter-microvm --lib tart::
nix develop .#macos-provider --command cargo test --locked -p ngit-ci-adapter-microvm --test tart_transportThe transport test uses a simulated Tart command with the real guest supervisor; it does not boot a macOS VM. These checks need no provider credentials and do not start services. Building macos-host-tools does not run tests; native tests and the deployment acceptance checks below remain separate requirements.
Build .#adapter-tart on Apple Silicon. Its ngit-ci-adapter-tart binary connects startup host/runtime checks, interrupted-job recovery, immutable component identity, one-slot admission and graceful shutdown to the normal adapter protocol. It never selects direct execution. Create its private home (mode 0700) and a separate socket directory owned by the adapter account and readable by the provider group (0750). The socket is 0660; the adapter leases both its home and socket directory, and refuses to replace an active, foreign or non-socket endpoint. Use a dedicated unprivileged account, not root.
Options use CLI > environment > .env > defaults. The environment prefix is NGIT_CI_ADAPTER_TART_; no secret values are accepted on the command line.
| CLI flag | Environment suffix | Default / requirement |
|---|---|---|
--environments | ENVIRONMENTS | Required JSON array of {template, socket, toolchain}, optional base-image and base-image-digest; one to eight entries |
--home | HOME | Required private APFS Tart home |
--binary | BINARY | Required absolute pinned Tart executable |
--softnet | SOFTNET | Required absolute pinned executable named softnet |
--vcpus | VCPUS | 4; leave at least one host logical CPU |
--memory-mib | MEMORY_MIB | 8192; leave at least 4096 MiB host headroom |
--boot-timeout-secs | BOOT_TIMEOUT_SECS | 180, positive |
--protected-address | PROTECTED_ADDRESSES | Complete management IPv4 inventory for general internet egress; mutually exclusive with --egress-address |
--egress-address | EGRESS_ADDRESSES | Alternative: 1–256 explicitly approved public service IPv4 endpoints; all other destinations denied; repeat flag or comma-separate values |
--log-level | LOG_LEVEL | info |
Choose the environments to offer
There is one Tart backend. Configure only the prepared templates you want to store and serve. toolchain: "swift" requires Apple's Command Line Tools/Swift and macOS SDK; toolchain: "xcode" additionally requires working full Xcode. The full-Xcode environment also advertises Swift, so a provider offering only Xcode needs just one template. Start with Swift on a space-constrained Mac. There is no automatic download, installation, smaller-image substitution or host execution fallback.
For two different prepared images, the adapter's .env contains one line:
dotenv
NGIT_CI_ADAPTER_TART_ENVIRONMENTS='[{"template":"clean-swift","socket":"/var/lib/ngit-ci-swift-socket/adapter.sock","toolchain":"swift"},{"template":"clean-xcode","socket":"/var/lib/ngit-ci-xcode-socket/adapter.sock","toolchain":"xcode"}]'Create each socket directory with the account/group/mode described below. Keep both templates under the same private Tart home and quota volume; run one adapter daemon, not one per image. Each template must occur once. Set the optional base-image to the upstream registry/repository name without a tag or digest, such as ghcr.io/cirruslabs/macos-tahoe-vanilla. It is advertised as /components/base-image-name so workflows can select a family independently of version. The installer should populate source fields from its verified acquisition receipt; they do not describe the local prepared template's name.
Set each offering's optional base-image-digest to the upstream OCI manifest digest used to prepare its template, for example sha256:eeec54bfe1f076e27786c5d92b89187a05b1d109b5071eb2dcdf02d596e34640 for the pinned macOS Tahoe vanilla base. This operator-declared source identity is published as /components/base-image; it is not a hash of the prepared disk or proof of its contents. Record it at acquisition, retain it through guest preparation, and change it when replacing the base. Omit it when provenance is unknown; mutable tags and malformed digests are rejected. No image is downloaded in response to this field.
Every endpoint has a separate leased directory. The --environments flag and NGIT_CI_ADAPTER_TART_ENVIRONMENTS environment variable accept the same JSON. They replace the unreleased single --template/--socket settings.
At startup, the adapter cold-clones each configured template, verifies root RPC, compiles and runs a small Swift program using Apple's SDK, and checks xcodebuild -version when Xcode was requested. It destroys each probe clone before checking the next template, and opens no endpoints unless all checks succeed. The probe repeats before each job payload. This verifies basic tooling, not particular simulator runtimes, signing identities or every Xcode feature. If supervisor capability negotiation fails before a job payload is sent, the adapter includes up to 4096 bytes of Tart startup stderr in the error. Stderr after payload submission is discarded to avoid exposing job secrets. An early transport EOF alone is not evidence that the template needs rebuilding. An Xcode installation configured as swift intentionally advertises only Swift.
Each endpoint publishes a configuration manifest: declared upstream base digest when known, checked runtime versions, policy settings, and boolean /configuration/apple-swift and /configuration/full-xcode capabilities. Existing environment requirements and exact-identity allocation checks select the endpoint; no new protocol fields are needed. Drain and restart when changing templates or configuration. Startup now includes a disposable boot per configured image, so allow for that before starting the providers.
Run one existing native provider worker per endpoint, with distinct OFFERING values (for example macos-swift and macos-xcode), distinct private working, state and log directories, and MAX_JOBS=1 for each. They may share the same provider signing identity and coordinator allowlist. Clone the supplied provider plist with distinct Label, WorkingDirectory, HOME and log paths; place each worker's .env in its own working directory and set ADAPTER_SOCKET to the matching endpoint. Keep the existing dedicated accounts and permissions. With one environment, use the single-worker recipe below unchanged except for the chosen template/toolchain and offering name.
These are alternative environments sharing one job slot, not additive host capacity. Admission at either endpoint takes the same slot; another allocation is rejected as busy before started, and unverified cleanup quarantines all endpoints. Disk admission uses total quota consumption (all stored templates, clones and temporary files). Adding an image reduces the remaining job budget; it does not create another quota or bypass the host reserve. The adapter never automatically prunes a configured template to make room.
Network isolation
Choose exactly one network mode. Restricted egress (--egress-address) permits only approved outbound /32 destinations and their stateful replies. It keeps the host/private-range/inbound blocks and adds a default deny for everything else. Approve only external service endpoints; this is an IP allowlist, not hostname or TLS enforcement. Jobs cannot extend it. DNS resolvers must also be explicitly allowed and configured in the guest. Changed CDN addresses fail closed until the operator reviews the list and restarts/requalifies the adapter. The environment identity binds both allow and block rules. This mode needs no public management-address inventory and still requires real packet/VM qualification.
For general internet egress, the protected-address inventory must include every host/management public IPv4 address and public NAT address; private ranges are always blocked. The daemon still trusts the completeness of this static inventory. Both modes install a fixed SystemConfiguration notification helper for the system's global IPv4, IPv6, DNS and proxy configuration before listening. A change, watcher exit or read failure closes admission and kills the tracked VM process group, independently of slow log consumers. Provisioning/execution then follows normal verified VM cleanup. A bounded readiness handshake must succeed after native notification registration and run-loop scheduling. The helper gets no provider environment or job-controlled input and reads no network values. It uses Apple's dynamic-store notification API directly: macOS 27 removed the previously used scutil n.wait command. Actual network-change teardown on the supported macOS release still needs qualification.
The helper reports only a bitmask of the fixed notification categories (IPv4, IPv6, DNS, proxies, empty callback, or unrecognized key); it never queries network values or prints arbitrary key names. Empty callbacks indicate a configuration server restart according to Apple's API contract. The parent consumes that byte before reaping the helper, so immediate exit cannot hide a buffered notification. Logs distinguish notifications, EOF without a notification, unexpected output and read errors, and record watcher uptime and bounded exit-status collection. Every case still invalidates admission immediately.
Invalidation writes .ngit-ci-network-requalification-required in the private Tart home. With restricted egress, ordinary IPv4, IPv6, DNS and proxy notifications produce a recovery record bound to the exact allow/block policy. The adapter closes admission, waits for connection handlers to finish VM cleanup and terminal reporting, then exits so launchd can restart it. Startup recovers interrupted job bundles, verifies the unchanged restricted policy and registers a fresh network watcher before retiring the record. Every template must pass disposable-VM qualification before sockets reopen. Wi-Fi off/on therefore needs no manual marker removal in this mode. An interrupted job is not resumed or automatically retried; the provider returns through its normal supervised startup.
General internet egress still relies on a manually reviewed host/management inventory. Its notifications require operator review, as do watcher failures, empty/unknown callbacks, malformed or unsafe recovery records, changed policy, and legacy quarantine markers. Stop both services, verify VM cleanup and review the address inventory and packet-filter policy before retiring such a marker and starting qualification. A marker-write failure closes admission but does not request automatic restart; durable quarantine cannot be assumed in that case. No recovery path relaxes network rules or clears provider cleanup quarantine.
Notifications are not an atomic packet-filter barrier. They cannot discover a router's public NAT address changing without a corresponding macOS state change, or changes while the daemon is stopped. Nor do they prove absence of a packet window before notification/VM teardown. These remain implementation and hardware qualification gates. Do not advertise a supported provider yet. The command line is for supervised qualification while those gates are completed. No NixOS/Compose service is added for this macOS-only executable; the supervised launchd installation recipe below remains unvalidated on hardware.
Prepare a clean template
Bounded storage for home and dedicated providers
Use one dedicated APFS volume with an enforced quota, containing both the clean template and job clones. Apple documents volume quotas as a limit on allocation, and same-volume clones as sharing unchanged blocks. A separate volume per clone would lose that sharing. The one-slot adapter therefore treats the volume's remaining quota as the upper bound on additional guest disk consumption. This is a whole-volume limit, including the template and runtime temporary files, not a per-file quota or a promise that all guest-visible virtual space can be written.
Startup and each allocation query Apple's diskutil plist output, converted by plutil, and require a writable, ownership-enabled, non-system APFS volume with a nonzero quota. The adapter pins the volume identity, mount and quota for its lifetime, rejects nested mounts redirecting its storage, and refuses missing or unrecognized quota information. Quota changes require draining and restarting. No root storage helper or quota-changing permission is granted to the adapter.
Admission requires both:
- At least 4 GiB remaining in the quota for boot/job writes. A job may need substantially more; exceeding the quota fails the job rather than borrowing unrestricted host space.
- APFS container free space of at least remaining quota + 16 GiB. The reserve covers the guest's maximum additional volume growth at admission. It is not a reservation against unrelated host applications allocating space later.
For example, a 24 GiB quota with 18 GiB physically used leaves at most 6 GiB for the next job and requires 22 GiB container free space. A 100 GiB virtual guest disk does not change that calculation. These are arithmetic examples, not measured macOS/template sizes. With 50 GB initially free, the template, job growth allowance, host Nix installation/build outputs and 16 GiB reserve must all fit. 50 GB is a qualification target, not a guaranteed supported minimum.
Create the new volume using Disk Utility's Add APFS Volume → Size Options → Quota Size, selecting the intended container; do not erase or repartition the existing disk. Choose the quota after measuring the template and build footprint. Keep the mount root administrator-owned, enable ownership, and create a private adapter-owned directory within it. The examples below use /Volumes/NGITCI/tart. After confirming this is the intended mounted volume, set its root to root:wheel mode 0755; do not give the service account administrator rights. The volume must mount before the adapter; a missing volume must fail startup, not turn into a fallback directory on the system disk. External APFS storage also requires disconnect/reconnect qualification.
The quota bounds VM storage and Tart temporary files. Provider artifacts, logs, the host Nix store and source-build outputs are outside it and must have their own limits/retention. Do not enable the optional cache for the first disk-constrained qualification. Exclude the disposable CI volume from backup snapshots during setup: retained snapshots can prevent deleted job blocks from being reclaimed; insufficient remaining quota then refuses further jobs.
Native quota qualification before enabling jobs
First create a separate disposable test APFS volume with a 64–256 MiB quota and an empty private directory writable by your normal test user. Keep at least 16 GiB plus the entire test quota free in its container. Do not use the real template volume for this test. Enable ownership and use a root:wheel 0755 mount root just as for the real volume. Set the directory path and run on the Mac:
bash
export NGIT_CI_APFS_QUOTA_TEST_HOME=/Volumes/NGITCIQuotaTest/private-test-directory
nix develop .#macos-provider --command cargo test --locked -p ngit-ci-adapter-microvm --lib native_quota_enforces_cow_growth_and_recovers_after_cleanup -- --ignored --nocaptureThe test refuses root, missing setup, a large/unlimited quota or a substantially occupied volume. It creates a private temporary directory, checks actual APFS clone sharing and original-file preservation, writes until the kernel returns quota/space exhaustion (bounded to at most 512 MiB even if enforcement fails), then verifies cleanup restores usable capacity. It never creates, formats, resizes or deletes volumes. Inspect a failure before removing any test volume. This test is intentionally ignored in ordinary/Linux suites: missing native prerequisites must fail an explicitly requested run, not fake a pass.
Then test a disposable VM filling its disk: require a failed job, unchanged template, no host-space exhaustion, verified clone destruction and a successful subsequent job. Test restart with an interrupted/full job, quota changes and a missing mount. Native APFS clone sharing, original preservation, quota exhaustion and cleanup recovery passed on macOS 27.0.1 with a disposable 128 MiB quota on 2026-10-21. VM exhaustion and recovery remain unqualified.
Guest software
Prepare a genuine Apple Silicon macOS guest. Install Nix and Git into /nix/var/nix/profiles/default/bin, ngit-ci's stdio supervisor/native job binary, and Tart's guest agent. The flake's Apple-Silicon-only macos-guest-tools package collects the ngit-ci guest executables, Nix, Git, SSH, Bash and CA certificates. Build it from the exact reviewed revision on Apple hardware, then install its resulting profile inside the guest (not on the provider host):
bash
nix build .#macos-guest-tools --out-link result-macos-guest-tools
sudo nix-env --profile /nix/var/nix/profiles/default --set ./result-macos-guest-toolsThis replaces the named guest profile; use a clean template and retain the previous profile generation for template preparation recovery. The package does not install host services, Tart's guest agent, Xcode or an Apple SDK. Its build and profile activation still require native hardware validation.
Install multi-user Nix inside the guest and wait for both its store mount and daemon socket after boot. Select the daemon explicitly for job clients, such as nix-build --store daemon; do not set a global store = daemon override in nix.conf, which also affects the daemon's own backing store. The fresh guest recipe retains the installer's daemon definition and provides a UUID-bound store mount job. Verify after a cold boot, not just against an already-running daemon. Root job clients otherwise select the local store. With Nix 2.34.7 on Darwin, local builds resolve the client's private TMPDIR after dropping to a build user and fail with Permission denied while setting up the build environment. Using the daemon preserves private job HOME/TMPDIR permissions and the separate nixbld build users. Do not make job workspaces traversable to work around this failure. Verify nix store info --json reports "url":"daemon", then perform an uncached derivation build with a root-owned mode-0700 HOME and TMPDIR before sealing the template.
Configure Tart's guest agent --run-rpc as a root launchd daemon inside the guest: ngit-ci's guest appliance currently expects root and /var/root. The usual login-user agent is not equivalent. Do not use --run-agent, which also enables clipboard sharing. See the guest agent's documented daemon/agent distinction. For the minimal template, install Apple's Command Line Tools with xcode-select --install inside the guest. Verify xcrun --sdk macosx --show-sdk-version and xcrun --sdk macosx swiftc --version. The basic qualification compiles a Swift command-line program against the macOS SDK; it does not need the full Xcode application or simulator runtimes. Install full Xcode only for workflows that require it, accept its terms and finish first-launch setup inside that template. Verify xcodebuild -version and run the separate full-Xcode canary; basic Swift success is not evidence that Xcode project builds, simulators or device signing work.
The prepared transport invokes only the fixed /nix/var/nix/profiles/default/bin/ngit-ci-vsock-agent --stdio through tart exec -i. Job commands, arguments and secrets use its framed stdin channel, never the host command line or environment. It reuses controlled stop and artifact streaming; VM boot, network admission and verified destruction must surround it. Transport tests alone do not establish that lifecycle boundary.
Create /etc/ngit-ci-job-template containing disposable-macos-job inside the guest. This is a canary prerequisite, not hardware attestation. Do not import personal Apple accounts, keychains, SSH identities, provider configuration or cloud credentials. Disable unnecessary login/screen-sharing services and all host folder, clipboard and USB sharing.
Use a standalone raw-disk local bundle (config.json, disk.img, nvram.bin), with owned regular files and no symlinks, hard links or shared write access. Stacked/ASIF layouts and retained manifests are not qualified: they can depend on state outside the bundle. The lifecycle checks both the template and clone and rejects saved memory, an overlay, a manifest or a control socket before use.
Shut down cleanly. Pin the disk, configuration and auxiliary-state identity. Never clone suspended/saved-memory state. A template update creates a new environment identity and requires requalification; never promote a previous job disk into the clean template.
Install host services for supervised qualification
The repository supplies adapter/provider system LaunchDaemon plists in deploy/macos/, plus an optional separate cache service described below. They run independently of a personal login, under different non-administrator accounts. This follows Apple's launchd service model. These files are prepared but have not been loaded on a Mac. Complete the network gate above before permitting repository jobs; installing files does not qualify the backend.
With an administrator, create dedicated standard, non-administrator accounts named
ngit-ci-adapterandngit-ci-providerusing System Settings or your normal account-management tooling. Give neither account an Apple ID, personal keychain, SSH agent, administrator membership or general passwordless sudo. Softnet's pinned installation requirements require privilege for network initialization. Use a root-owned SUID copy of the verified binary with mode 4750, in a root-owned directory, and a dedicatedngit-ci-networkgroup containing only the adapter account. Do not use the shared execution group for this permission. Do not grant provider/cache accounts access to this helper or passwordless sudo. Softnet is a trusted privileged host component, never guest software; its privilege drop does not make unrestricted invocation by other accounts safe. The pinned CLI also accepts explicit target user/group arguments. Recheck ownership, mode, ACLs and group membership after every runtime update.Build the exact reviewed revision on Apple Silicon and root its host profile:
bashnix build .#macos-host-tools --out-link result-macos-host sudo nix-env --profile /nix/var/nix/profiles/ngit-ci-host --set ./result-macos-hostThis profile contains the provider, adapter and optional cache worker, its pinned Nix helper and service files. Guest commands use the separate guest profile described above.
Create the shared socket group and private state directories:
bashsudo dseditgroup -o create ngit-ci-execution sudo dseditgroup -o edit -a ngit-ci-adapter -t user ngit-ci-execution sudo dseditgroup -o edit -a ngit-ci-provider -t user ngit-ci-execution sudo dseditgroup -o create ngit-ci-network sudo dseditgroup -o edit -a ngit-ci-adapter -t user ngit-ci-network sudo install -d -o ngit-ci-adapter -g ngit-ci-execution -m 0700 /var/lib/ngit-ci-tart # Verify NGITCI is the mounted, quota-limited APFS volume created above first. test -d /Volumes/NGITCI test "$(stat -f %d /Volumes/NGITCI)" != "$(stat -f %d /Volumes)" sudo install -d -o ngit-ci-adapter -g ngit-ci-execution -m 0700 /Volumes/NGITCI/tart sudo install -d -o ngit-ci-adapter -g ngit-ci-execution -m 0750 /var/lib/ngit-ci-tart-socket sudo install -d -o ngit-ci-provider -g ngit-ci-execution -m 0700 /var/lib/ngit-ci-provider sudo install -d -o root -g wheel -m 0755 /var/log/ngit-ciFor an existing installation, verify existing group membership and ownership rather than recreating accounts or changing unrelated directories. The socket directory persists across reboot and contains no keys. Keep the log directory root-owned so service accounts cannot replace log paths with symlinks.
Create each account's
.envin its working directory with mode 0600 and ownership matching that account. Use an editor or your secret manager; never put actual keys into a shell command, plist, Git file or Nix expression. The adapter's/var/lib/ngit-ci-tart/.envcontains operator configuration:dotenvNGIT_CI_ADAPTER_TART_ENVIRONMENTS='[{"template":"clean-macos","socket":"/var/lib/ngit-ci-tart-socket/adapter.sock","toolchain":"swift"}]' NGIT_CI_ADAPTER_TART_HOME=/Volumes/NGITCI/tart NGIT_CI_ADAPTER_TART_BINARY=/absolute/pinned/path/to/tart NGIT_CI_ADAPTER_TART_SOFTNET=/absolute/pinned/path/to/softnet NGIT_CI_ADAPTER_TART_PROTECTED_ADDRESSES=REPLACE_WITH_COMPLETE_IPV4_INVENTORY NGIT_CI_ADAPTER_TART_VCPUS=4 NGIT_CI_ADAPTER_TART_MEMORY_MIB=8192Prepare the cold template in this dedicated
TART_HOME, owned by the adapter account. The provider's/var/lib/ngit-ci-provider/.envcontains:dotenvNGIT_CI_PROVIDER_SECRET_KEY=REPLACE_PRIVATELY_WITH_DEDICATED_PROVIDER_KEY NGIT_CI_PROVIDER_OFFERING_ID=macos-swift NGIT_CI_PROVIDER_SYSTEM=aarch64-darwin NGIT_CI_PROVIDER_ADAPTER_SOCKET=/var/lib/ngit-ci-tart-socket/adapter.sock NGIT_CI_PROVIDER_STATE_DIR=/var/lib/ngit-ci-provider/state NGIT_CI_PROVIDER_WORK_DIR=/var/lib/ngit-ci-provider/work NGIT_CI_PROVIDER_MAX_CONCURRENT_JOBS=1 NGIT_CI_PROVIDER_ALLOWED_COORDINATORS=REPLACE_WITH_ALLOWED_COORDINATOR_PUBLIC_KEY NGIT_CI_PROVIDER_RELAYS=wss://REPLACE_WITH_RELAY NGIT_CI_PROVIDER_BLOSSOM_SERVERS=https://REPLACE_WITH_BLOSSOM_SERVER NGIT_CI_PROVIDER_MANAGED_CACHE=falseDisabling the managed cache is only the initial cold-run qualification stage: upstream public cache reads remain enabled. Shared cache publication and credential separation require a separate qualification pass before this recipe is considered production-ready. Do not open host cache ports through Softnet as a shortcut. Provider options remain documented in the native provider guide.
Check that any existing log paths are regular files, not symlinks or unexpected files. Pre-create fresh logs without truncating existing logs, make each 0600 and owned by its service account, then install the plists:
bashsudo touch /var/log/ngit-ci/adapter.log /var/log/ngit-ci/provider.log sudo chown ngit-ci-adapter:ngit-ci-execution /var/log/ngit-ci/adapter.log sudo chown ngit-ci-provider:ngit-ci-execution /var/log/ngit-ci/provider.log sudo chmod 0600 /var/log/ngit-ci/adapter.log /var/log/ngit-ci/provider.log sudo install -o root -g wheel -m 0644 result-macos-host/share/ngit-ci/launchd/dev.ngit.ci.adapter.plist result-macos-host/share/ngit-ci/launchd/dev.ngit.ci.provider.plist /Library/LaunchDaemons/ plutil -lint /Library/LaunchDaemons/dev.ngit.ci.adapter.plist /Library/LaunchDaemons/dev.ngit.ci.provider.plistArrange privileged log rotation before unattended use; the supplied files do not bound accumulated log storage. Core dumps are disabled. Each daemon gets a restrictive umask, 30-second restart throttle and up to one hour for graceful termination. The adapter starts through
/usr/bin/caffeinate -is: idle system sleep is inhibited while it runs, with an additional system-sleep assertion on AC power. Display sleep remains allowed. Stopping the adapter releases its assertions; no persistent power settings are changed. Manual sleep, lid closure and shutdown are not prevented reliably by this policy. Verifypmset -g assertionsshows the adapter's caffeinate assertions before admitting jobs, and that they disappear after stopping it. Asleep 0setting alone is insufficient evidence: native testing observed maintenance-sleep cycles despite that setting. Sleep/wake recovery and in-flight launchd drain still need native validation.After the network gate is met, bootstrap the adapter, inspect its startup log and socket ownership, then bootstrap the provider:
bashsudo launchctl bootstrap system /Library/LaunchDaemons/dev.ngit.ci.adapter.plist sudo launchctl print system/dev.ngit.ci.adapter sudo launchctl bootstrap system /Library/LaunchDaemons/dev.ngit.ci.provider.plist sudo launchctl print system/dev.ngit.ci.providerThe provider refuses startup without a hardware-VM description; launchd retries if the adapter is still hashing its template. No startup ordering assumption enables host execution. Keep the coordinator's production allowlist unchanged until the acceptance workflow and negative tests pass.
For an upgrade, stop admission and launchctl bootout the provider first, then the adapter. Wait for their processes and job bundles to disappear through normal cleanup; do not use a force-kill shortcut. Change the rooted profile and review configuration, then bootstrap adapter and provider in that order. Retain the prior profile generation for rollback. Requalification is required when runtime, template or network identity changes. A home Mac also needs an explicit sleep/logout/network-change trial; a dedicated host needs a reboot-recovery trial.
Optional shared cache publication (qualification only)
The host profile also supplies dev.ngit.ci.cache.plist and share/ngit-ci/cache.example.json. This uses the existing separate-account cache worker with an external S3 destination. Guests read signed objects through the bucket's public HTTPS cache endpoint; they receive neither upload credentials nor the cache signing key. This avoids opening Mac host ports through Softnet. A home installation can retain upstream read-only caching while this optional service is qualified.
The pinned Darwin Nix derivation enables AWS authentication dependencies, but that is an evaluation result, not a successful native S3 transfer. Test the exact installed binary, endpoint and credentials on the Mac before enabling publication. External mode publishes authorized shared outputs only; it does not provide managed-cache inventory, temporary PR namespaces or local retention maintenance. Configure remote storage lifecycle/cost limits separately. Do not publish sensitive outputs into a public cache.
Create a third standard non-administrator account
ngit-ci-cache, with no Apple ID, personal keychain, SSH agent, sudo or Softnet access. Create its socket group and directories:bashsudo dseditgroup -o create ngit-ci-cache sudo dseditgroup -o edit -a ngit-ci-cache -t user ngit-ci-cache sudo dseditgroup -o edit -a ngit-ci-provider -t user ngit-ci-cache sudo install -d -o ngit-ci-cache -g ngit-ci-cache -m 0700 /var/lib/ngit-ci-cache sudo install -d -o ngit-ci-cache -g ngit-ci-cache -m 0750 /var/lib/ngit-ci-cache-socket sudo install -o ngit-ci-cache -g ngit-ci-cache -m 0600 result-macos-host/share/ngit-ci/cache.example.json /var/lib/ngit-ci-cache/cache.jsonInspect existing directories/groups rather than replacing them. Restart the provider after changing supplementary groups. Verify group lookup under its actual launchd identity; successful interactive access alone is insufficient.
Edit the private JSON file to select a dedicated cache bucket and region. Supply a cache-only Nix signing key and a cache-scoped AWS shared-credentials file at the configured paths, both mode 0600 owned by
ngit-ci-cache. Use your secret manager/editor; do not put values in plists or shell history. Restrict the upload identity to the cache bucket and required object actions. The example allows a 512-MiB export and requires 16 GiB free in addition to incoming bytes. These are starting values, not a disk quota: reserve space for the provider's export and worker's copy as well as the job VM.Prepare
/var/log/ngit-ci/cache.logas a regular mode-0600 file owned byngit-ci-cache, with privileged rotation, following the earlier log rules. Install and bootstrap only this additional service:bashsudo install -o root -g wheel -m 0644 result-macos-host/share/ngit-ci/launchd/dev.ngit.ci.cache.plist /Library/LaunchDaemons/ plutil -lint /Library/LaunchDaemons/dev.ngit.ci.cache.plist sudo launchctl bootstrap system /Library/LaunchDaemons/dev.ngit.ci.cache.plist sudo launchctl print system/dev.ngit.ci.cacheAfter checking worker startup and socket permissions, replace the provider's cold-cache setting in its private
.env:dotenvNGIT_CI_PROVIDER_MANAGED_CACHE=true NGIT_CI_PROVIDER_CACHE_WORKER_SOCKET=/var/lib/ngit-ci-cache-socket/worker.sock NGIT_CI_PROVIDER_CACHE_SUBSTITUTERS=https://REPLACE_WITH_PUBLIC_CACHE_ENDPOINT NGIT_CI_PROVIDER_CACHE_TRUSTED_PUBLIC_KEYS=REPLACE_WITH_CACHE_PUBLIC_KEYRetain any other intended public substituters/keys using the documented comma-separated option format. Restart through normal provider drain. A missing worker fails provider startup; it never moves publication back into the provider. During upgrades, drain the provider before stopping its cache worker, then start the worker before restarting the provider.
Before support, prove native Unix peer authentication, unauthorized-peer denial, mutual credential-file denial, signed publication and reuse by a fresh job VM, request cancellation, staging removal, and recovery after worker interruption. Keep upload/signing credentials absent from guests and provider environments. This launchd recipe provides account separation; it does not reproduce the NixOS worker's private mount view or cgroup limits. Qualify native resource pressure and host-service exposure separately. The supplied files have not yet been loaded on Apple hardware; installing them does not pass these gates.
Validate through ngit-ci
The manual-only .ngit/nix/workflows/macos-isolation.yaml requires aarch64-darwin and Tart, disables result reuse, compiles/runs Swift with Apple's macOS SDK, checks a fresh marker and passes a report through declared artifact input to a second job. It has no Linux fallback and has not yet run on Apple hardware. It supports a Command-Line-Tools-only guest. The separate manual .ngit/nix/workflows/macos-xcode.yaml additionally requires a working /configuration/full-xcode: {eq: true} and checks xcodebuild -version. A CLT-only offering does not match; without a matching provider the workflow cannot allocate. The basic workflow requests /configuration/apple-swift: {eq: true}, which both environments provide. Use a real project after that tooling check to qualify the particular Xcode/SDK features your jobs need.
After adapter installation and network qualification, allowlist the test provider on the coordinator. Leave the secret-provider allowlist empty for the first run. Pin its actual environment in coordinator selection defaults and trigger the exact PR revision with an authorized signer:
bash
ngit ci trigger <coordinator-npub> <exact-commit> \
--workflow .ngit/nix/workflows/macos-isolation.yaml --json
ngit ci status <exact-commit> --jsonInspect signed results and artifact contents. Repeat: each VM must start without the previous marker. Observe distinct bundles and prove both are stopped and deleted before capacity returns. Retain runtime/image identity, exact commit and host evidence alongside the report. Then exercise these gates:
| Scenario | Required evidence |
|---|---|
| Dummy secret | Only its authorized job receives it; absent from next job, template, logs and unintended artifacts |
| Network denial | TCP, UDP, IPv6 and spoofed packets cannot reach host management, LAN, metadata or other jobs; public dependency fetch works |
| Cancel/timeout | Graceful and forced stop terminate descendants, preserve permitted partial artifacts and delete the VM |
| Crash/restart | Interrupted bundles are reaped before advertising; uncertain cleanup quarantines capacity |
| Missing backend/policy or changed template | Clear startup/admission failure; no direct fallback |
| Privileged network helper | Only the adapter account can execute the pinned SUID Softnet; provider/cache accounts cannot, including through ACLs or alternate privileged copies |
| Resource pressure | Reserves prevent over-admission; a full guest disk cannot exhaust the personal host |
| Home lifecycle | Sleep/wake, logout and Wi-Fi/VPN changes preserve isolation or safely withdraw capacity |
| Apple tooling | Record boot/build/teardown times, peak host/guest RAM and disk growth |
Use dummy secrets and controlled listeners. Guest canaries cannot prove their own hypervisor boundary: retain host process, disk and network evidence. Add a longer Xcode project and required Metal workload after boundary tests pass. Increasing concurrency requires renewed resource and licensing qualification.
Updates and recovery
Drain before runtime/template updates. Retain the previous pinned components for rollback, but never resume a job snapshot. Check cleanup and identity before restoring admission. If cleanup is uncertain, leave capacity unavailable and inspect only adapter-owned bundles; do not delete unrelated VMs or a personal Tart home. Failed qualification must never enable direct host execution.