Document macOS agent installation

[welteki]

Description

Add installation and enrollment instructions for the native macOS agent.

Document automatic and manual base-image preparation.

Motivation and Context

Provide a complete onboarding path for running the Actuated agent on Apple
Silicon.

• I have raised an issue to propose this change (required)

How Has This Been Tested?

• Rendered the documentation using the MkDocs Material Docker image.
• Reviewed both macOS pages through the live preview.
• Checked the documented commands against the tested end-to-end installation
  workflow.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTION guide
• I have signed-off my commits with git commit -s

[derek]

Thank you for your contribution. unfortunately, one or more of your commits are missing the required "Signed-off-by:" statement. Signing off is part of the Developer Certificate of Origin (DCO) which is used by this project.

Read the DCO and project contributing guide carefully, and amend your commits using the git CLI. Note that this does not require any cryptography, keys or special steps to be taken.

💡 Shall we fix this?

This will only take a few moments.

First, clone your fork and checkout this branch using the git CLI.

Next, set up your real name and email address:

git config --global user.name "Your Full Name"
git config --global user.email "you@domain.com"

Finally, run one of these commands to add the "Signed-off-by" line to your commits.

If you only have one commit so far then run: git commit --amend --signoff and then git push --force.
If you have multiple commits, watch this video.

Check that the message has been added properly by running "git log".

[welteki]

Medium: New workflow sample uses actions/checkout@v7

actions/checkout@v7 is valid. Other pages using v4 does not make the new example incorrect.

[alexellis]

The base image page predates two changes that landed on openfaasltd/actuated-macos a couple of hours after your last push here, so the provisioning story on this page is now a tier short.

1. base provision installs Command Line Tools as well as the runner

Since v0.0.10 it runs two steps, CLT first and then the runner. A stock guest has no git, clang or swiftc at all, so before that change even actions/checkout failed on a freshly provisioned base — which is what prompted it. No Apple ID and no GUI are involved; it takes about 70s and 1.9GB, and it is idempotent, reporting clt-already-installed when the tools are already there.

Two spots need a word adding:

• "install the GitHub Actions runner into the base image" → "install the Command Line Tools and the GitHub Actions runner"
• "The prepared base image now contains the GitHub Actions runner." → "…contains the Command Line Tools and the GitHub Actions runner", and it is worth naming git, clang and swiftc explicitly, since "Command Line Tools" does not obviously imply "checkout will now work".

2. There is a second tier, agent base xcode, which the page does not mention

New in v0.0.11. It takes a provisioned base and layers on the host's own Xcode plus a platform SDK:

~/.actuated/bin/agent base xcode \
  --from ~/.actuated/base.bundle \
  --to ~/.actuated/base-xcode.bundle

Points worth making, because they are the ones people get wrong:

• The host's /Applications/Xcode.app is the source. Nothing is downloaded from Apple and no credentials enter the guest. The platform SDK download (xcodebuild -downloadPlatform iOS) is unauthenticated.
• The host's Xcode licence does not need to be accepted. I confirmed this today on a host where xcodebuild refuses to run for exactly that reason — the guest accepts its own licence during the build, so it is not a prerequisite.
• Budget 6–10 minutes. Measured 5m56s on an M4 mini today, and you saw 9m11s. Nearly all of it is extracting Xcode's ~120k files and pulling the SDK.
• Disk: Xcode 26.6 is 8.4GB archived. du claims 3.7GB, but that is APFS dedup and not what you need free.
• It installs to a versioned path, /Applications/Xcode_26.6.app, with /Applications/Xcode.app symlinked to it, matching what setup-xcode and most workflows expect.

3. One base per host — worth stating explicitly

handleDispatch takes a single base; job labels are logged but never used to select an image. So a host either serves the plain tier or the Xcode tier, and pointing it at the latter means every job on that host gets Xcode. It is a superset, so nothing breaks — I moved a host over today and its ordinary Go build went 1m6s → 1m8s — but the choice belongs on this page rather than being discovered later.

Wiring it up is just the existing --base flag from the install page:

--base ~/.actuated/base-xcode.bundle

4. One naming caution

Please don't introduce base-clt.bundle as a tier name. It only exists as a retrofit for images built before v0.0.10, when CLT had to be added by hand. On any host set up from these docs the plain base.bundle already is the CLT tier, so the two names to document are base.bundle and base-xcode.bundle.

5. Verification

The existing smoke test is still right. For the Xcode tier it is worth one extra line on the clone, since a missing SDK will not show up in agent-health:

~/.actuated/bin/agent vm exec \
  --bundle ~/.actuated/smoke.bundle -- xcodebuild -version

Structurally I would keep this as one page with a "Choose an image tier" section near the top — plain for everything that is not an iOS build, Xcode for the rest — rather than splitting it, since the Xcode tier is built from the output of the steps already documented here.

[alexellis]

The sync looks good — CLT is called out in the intro, the Xcode section covers --from/--to, the 6–10 minute expectation and the fact that base.bundle is left untouched. Four follow-ups, one of which is a question you raised yourself.

1. How Xcode is written

Checked against Apple's own artefacts rather than memory, since it came up:

Source	Spelling
CFBundleName, CFBundleDisplayName, CFBundleExecutable	Xcode
CFBundleIdentifier	com.apple.dt.Xcode
xcodebuild -version banner	Xcode 26.6
Apple's own licence prose (License.rtf)	Xcode ×7, no other form

So it is Xcode — capital X, lowercase c. XCode appears nowhere in anything Apple ships.

This PR is already correct throughout: prose uses Xcode, and every lowercase xcode is a genuine identifier (xcode-select, agent base xcode, --xcode-version, --xcode-app, base-xcode.bundle). grep -roE '\bXCode\b' returns nothing here or in actuated-macos. Worth stating plainly because the suggested heading text used XCode, which is the one variant to avoid.

2. Heading rename

## Prepare a base image with Xcode → ## Add Xcode into the base image, no trailing full stop, which matches the other headings on the page (Choose an image preparation method, Verify the base image).

3. Intro wording

The suggested rewrite is a better opening — it explains why there is no image to download, which the current text leaves implicit. One factual tightening: it reads as though two stages install the CLT, and it drops the runner. The stages are actually:

1. base create + base oobe — install macOS, complete Setup Assistant, install the guest agent
2. base provision — Command Line Tools and the GitHub Actions runner, one stage
3. base xcode — optional, Xcode plus a platform SDK

So "two additional stages" is right, but the CLT and the runner arrive together in the first of them. Worth keeping "Actuated does not distribute macOS due to restrictions in the EULA limiting redistribution" — that is a stronger reason than the current phrasing gives.

4. The verify block — I think you are half right to cut it

Your instinct to drop it is correct for the plain base. It duplicates the test build, and a base that cannot boot will fail loudly at the first job anyway, so four commands buys very little.

It is not redundant for the Xcode tier, though. The test build is a generic specs job — it never invokes xcodebuild, so a base with Xcode installed but the platform SDK missing passes it and then fails somebody's iOS build several minutes in, with a much worse error. That is exactly the failure the check would catch.

The honest reason the block looks so complicated is that the CLI has no composite verb, so the docs have to spell out clone → run → health → rm by hand. Rather than documenting four commands or dropping the check entirely, I would rather fix that end: a single agent base verify --bundle <bundle> that does the whole cycle and cleans up after itself. It can tell on its own whether the SDK check applies, because a sealed Xcode bundle records xcode_version and xcode_build in its config.json.

Suggestion: cut the block now as you proposed, and leave the Xcode section saying the first iOS build is the real test. I will follow up with the single command and then this page gets one line back instead of four.

[reviewfn]

AI Pull Request Overview

Disclaimer: This review was generated by automated AI and may contain errors. Do not trust its outputs without human verification.

Summary

• Adds a new macOS agent installation guide covering host preparation, enrollment, service setup, verification, and updates.
• Adds a new macOS base image preparation guide covering automatic, manual, Xcode, and verification flows.
• Updates the Linux agent page to point Apple Silicon users to the new macOS guide.
• Adds the macOS pages to the MkDocs navigation under Onboarding.
• Updates the MkDocs Material emoji extension import path and adds a Docker-based local preview command.
• The new content is mostly coherent, but a few reproducibility and publish-quality issues remain.

Approval rating (1-10)

7/10. The documentation is useful and structured, but onboarding can still block readers who lack arkade or need to verify an Xcode image.

Summary per file

Summary per file

File path	Summary
README.md	Adds Docker command for serving the MkDocs site locally.
docs/install-agent.md	Clarifies that the existing install guide is for Linux hosts.
docs/install-macos-agent.md	Adds end-to-end macOS agent installation and enrollment instructions.
docs/prepare-macos-base.md	Adds base image creation, provisioning, Xcode, and verification instructions.
mkdocs.yml	Updates Material emoji imports and adds macOS agent docs to navigation.

Overall Assessment

This is a solid documentation addition for a new macOS agent workflow. The pages are scoped well, the navigation placement makes sense, and the split between agent installation and base-image preparation keeps the flow manageable. The main merge risk is not rendering safety; it is reproducibility for first-time readers following the commands exactly. The guide should close two gaps before publication: it should show how to install arkade before using it, and it should make Xcode bundle verification explicit for readers who create base-xcode.bundle.

Detailed Review

Detailed Review

Content review

No blocking findings.

Medium: The macOS install guide depends on arkade but does not show how to install it

docs/install-macos-agent.md:15 lists arkade as a prerequisite, and docs/install-macos-agent.md:44 immediately uses arkade oci install, but the page never gives an installation command. This is a reproducibility gap for the stated end-to-end onboarding path: a reader starting from a fresh Apple Silicon Mac will fail at the first agent download step unless they already know how to install arkade.

Add a short command or explicit install path before the first arkade usage, for example:

curl -sLS https://get.arkade.dev | sudo sh

If Homebrew is the preferred macOS path, document that instead, but the guide should not rely on the external link alone for a required tool.

Medium: Xcode image verification is described, but the command only verifies the non-Xcode bundle

docs/prepare-macos-base.md:149 explains that an agent cannot select images per job and shows creating ~/.actuated/base-xcode.bundle. The verification section then only shows:

~/.actuated/bin/agent base verify \
  --bundle ~/.actuated/base.bundle

At docs/prepare-macos-base.md:168, the text says verification checks Xcode when an Xcode bundle is selected, but the page never shows readers how to select the Xcode bundle for verification. A reader preparing an Xcode-capable runner could verify only the default base image, install the unverified Xcode image in the service, and miss Xcode or platform SDK provisioning issues until jobs start failing.

Add an explicit Xcode verification example after the base verification command:

~/.actuated/bin/agent base verify \
  --bundle ~/.actuated/base-xcode.bundle

Low: The base image introduction has confusing subject/action wording

docs/prepare-macos-base.md:3 says the restore image "will be booted, and walk through the setup wizard, and install actuated's guest agent." The restore image itself cannot walk through setup or install the guest agent; the operator or automatic setup flow does that. This is in the opening paragraph, so the ambiguity affects reader confidence before the workflow starts.

Consider tightening it to something like:

The agent boots the restore image, completes macOS Setup Assistant, and installs actuated's guest agent. It then provisions Apple's Command Line Tools and the GitHub Actions runner. You can optionally create a second base image with Xcode for native Apple-platform builds.

Observations

The title and excerpt of the new macOS install page match the content: it promises installation, base image preparation, enrollment, and a test job, and the sections follow that sequence.

The split between install-macos-agent.md and prepare-macos-base.md is appropriate, but the cross-links make the reader bounce between pages. The return links help, and they should remain if either page is reorganized.

The automatic/manual tab structure is a good fit for the base-image page because the two paths are mutually exclusive and lead to the same ~/.actuated/base.bundle outcome.

The actions/checkout@v7 workflow example is inconsistent with the rest of the docs, which mostly use actions/checkout@v4. If that version is intentional, no action is needed; if not, aligning the example with the rest of the docs would reduce reader distraction.

AI agent details.

Agent processing time: 1m30.297s
Environment preparation time: 3.373s
Total time from webhook: 1m37.085s