Skip to content

Install a macOS provider ​

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.

Release-candidate installation guide. See the qualification reference for dated test evidence and limitations; source-level implementation is not a guarantee that every macOS host or workload is supported.

Use an Apple Silicon Mac to run one disposable macOS job at a time for a coordinator on your VPS. The coordinator does not need to run on the Mac. Managed cache publication is disabled; guest downloads from upstream Nix caches and artifact uploads remain available.

The native setup helper creates the service accounts, keychain, storage and services. Nix and Apple Command Line Tools are installed inside the guest; you do not need Nix, Rust, Python or Homebrew on the host.

This version uses a reviewed JSON configuration and a short command sequence. An interactive wizard, menu-bar app, automatic updates, additional image families and concurrent macOS jobs are later work. See the installation design for that direction; it is not a list of commands required here.

Before starting ​

  • Apple Silicon, macOS 26 or newer, administrator access and APFS storage.
  • An approved coordinator public key, shared relay URLs and an artifact server.
  • At least an 8 GiB guest budget plus a 4 GiB host reserve for the qualified configuration; leave more room for other applications where needed.
  • Space for the guest and job writes. The tested vanilla upstream download is about 24 GB compressed and its virtual disk is 50 GB. Download size is not free-space required. The 64 GiB CI quota is an enforced budget, not a guarantee every workload fits. Allow host reserve and preparation/retained-image headroom.
  • A reviewed network policy. Job egress and the guest's temporary Apple-download access are separate. Prepared guests use public DNS resolver 1.1.1.1; the selected policy must permit it. Preparation sets this explicitly and cold-boot qualification verifies it. The helper does not silently choose unrestricted egress.

Keep the Mac powered and connected during preparation. The display may sleep. Remote setup works over verified SSH; keep the administering terminal connected. Do not change sudo permissions just to run the installer.

1. Obtain and verify the release inputs ​

Authenticate the project's release publisher and checksum-list digest before running its binaries. Download the adapter/setup, Nix provider and guest-tools archives for the same version. Provider-only setup does not need the coordinator archive. Use the system checksum tool to authenticate the adapter archive against that verified list before extracting and executing its setup helper.

Extract the authenticated adapter and provider archives into separate directories called adapter and provider; keep the original archives and SHA256SUMS in downloads. The helper needs the directory containing each manifest.json, not its parent. Check all three input archives together:

sh
./adapter/ngit-ci-macos-setup release-verify \
  --directory ./downloads --checksums ./downloads/SHA256SUMS \
  --sha256 <authenticated-checksum-list-digest> --version <release-version>

Download the pinned third-party archives locally: Tart 2.41.1, Softnet 0.24.1, Nix 2.35.3 for ARM64 Darwin, and Tart guest-agent v0.15.0's Darwin universal archive. Review the Tart/Softnet licensing scope for your use before acknowledgement. Their hashes are embedded in the release helper and checked again during setup. A newer download with a different hash is not an interchangeable input.

The guest image is acquired by the helper at its configured upstream digest. It does not adopt your personal Tart VMs or replace unrelated runtime installs.

2. Review one choices file ​

Create provider-choices.json using the complete example and field reference. It contains public coordinator and endpoint information, resource limits, an APFS container UUID, reviewed egress addresses, and absolute local guest archive paths. It contains no signing key or keychain password. Leave max_jobs at 1 and select one vanilla image with intent: "create".

Generate the full installation intent from your choices and verified archives:

sh
./adapter/ngit-ci-macos-setup install-config \
  --choices ./provider-choices.json \
  --directory ./downloads --checksums ./downloads/SHA256SUMS \
  --sha256 <authenticated-checksum-list-digest> --version <release-version> \
  --acknowledge-dependency-licenses > ./provider-intent.json

Check this command succeeded before using the output file. Then review the plan and host checks:

sh
./adapter/ngit-ci-macos-setup install-plan --config ./provider-intent.json
./adapter/ngit-ci-macos-setup install-preflight --config ./provider-intent.json

A valid plan describes intended work; it does not certify installed resources or coordinator approval. Keep this exact intent for preparation, retries and startup.

3. Prepare and activate ​

Run the two administrator operations in sequence:

sh
sudo ./adapter/ngit-ci-macos-setup install-prepare \
  --config ./provider-intent.json \
  --adapter-source ./adapter --provider-source ./provider \
  --tart-archive ./downloads/tart-2.41.1.tar.gz \
  --softnet-archive ./downloads/softnet-0.24.1.tar.gz

sudo ./adapter/ngit-ci-macos-setup install-activate \
  --config ./provider-intent.json

Preparation creates dedicated identities and private credentials, a quota volume, verified runtime copies and one vanilla-based guest. It installs guest Nix and CLT, configures guest Nix clients to use the daemon, checks builds from a private working directory, removes preparation payloads and performs an offline cold boot. Apple package discovery/download can be slow. The configured deadlines are bounded; retain the reported evidence if preparation fails.

A successful preparation retry verifies completed checkpoints without repeating the image download or guest boot. After a failure, follow the reported recovery condition; do not delete receipts, change intent or blindly repeat an interrupted attachment/clone. Activation requires completed preparation and qualifies the adapter before starting the provider.

4. Connect it to the VPS coordinator ​

After activation, obtain the public identity from the fixed readiness message:

sh
sudo /usr/bin/grep 'Nix provider ready' /var/lib/ngit-ci-provider/service.log

The provider= field is a public key, not a credential. Exchange it with the coordinator operator, who must add it to the coordinator's compute-provider allowlist. Your choices already restrict which coordinator the provider accepts. This does not grant repository-secret access; that trust is separate.

Run an authorized macOS workflow through that coordinator and verify its signed result and uploaded artifact. A running launchd process alone is not proof that jobs can be delegated. The release workflow's downstream Linux verification is a useful end-to-end check when the coordinator has Linux capacity too.

Daily operation and stopping ​

sh
./adapter/ngit-ci-macos-setup services-status --live
sudo ./adapter/ngit-ci-macos-setup services-stop
sudo ./adapter/ngit-ci-macos-setup services-start

Stop refuses new admission and drains active work before removing the service registrations. Start requalifies the adapter before admission. Neither operation deletes credentials, images or job history. Live status reports service state; use the coordinator's CI result to assess individual jobs.

Restricted-egress providers automatically drain and requalify after ordinary Wi-Fi/network configuration notifications. Interrupted jobs are not resumed. Other quarantine causes still need review; see the network recovery rules.

After an interrupted stop, repeat stop. After interrupted start, either stop or retry start. Preserve evidence if drain cannot verify safety; do not force-stop a VM or clear quarantine merely to make services look healthy. Version replacement and its compatible rollback remain explicit administrator operations described in the implementation reference; automatic upgrades are not provided.

Deactivate while keeping your images ​

For an installation created by this first-install path:

sh
sudo ./adapter/ngit-ci-macos-setup install-deactivate

This drains work and removes only the installation's two service definitions. It retains accounts, credentials, images, quota storage, runtimes and receipts. It is deliberately not a destructive purge. Do not manually delete resource journals or the permanent non-secret numeric UID reservations: macOS login-keychain state can outlive account deletion, and setup must not recycle those identities.

Existing-service replacement uses services-rollback to restore its retained baseline; that is different from deactivating a first installation. Preserve compatible recovery tools and configuration when replacing a version.

Advanced setups and limits ​

Coordinator-only or combined-role setup remains an advanced implementation reference. A local coordinator can delegate Linux work to a remote Linux provider; this Tart provider advertises ARM64 macOS only. No automatic local pairing, Linux-on-Mac backend, full-Xcode image chooser or parallel job wizard is included.

Fresh installation does not adopt legacy/manual service accounts or personal storage. Moving an old deployment into this path needs a separately reviewed migration. Abrupt power loss and network quarantine must not be confused with a successful graceful maintenance test; see the recorded qualification limits.

Supervisor startup transport ​

Before admitting a booted guest, the adapter also launches the fixed supervisor with closed stdin and waits for a successful exit. Root RPC and Apple tools can be available before the separate Nix volume; this readiness check shares the existing provisioning deadline and cancellation path. A missing or broken supervisor therefore fails provisioning rather than admitting an unready guest.

If Tart closes the supervisor connection before replying to the capability probe, the adapter reaps the old helper and reconnects, for at most three attempts. No job input or execution request has been sent at this point. The five-second handshake deadline applies to each attempt; cancellation stops startup promptly. Malformed or unsupported capability responses, handshake timeouts, and unverified helper cleanup fail closed. Once capabilities are accepted, the adapter never replays input or execution, even if the connection closes immediately afterward. Persistent startup failures retain bounded pre-payload diagnostics and the helper exit status. This handles transient connection closure; it does not establish why Tart closed the original connection.