Native Mac nodes
canopy forest join makes a Mac a native compute node of your team: it enrolls, heartbeats,
exposes its Metal GPU and runs jobs next to the rest of your Forest. It is available to every team.
What you need
Section titled “What you need”- An Apple silicon Mac on macOS 14 or newer, with an administrator account and about 2 GiB of free disk (more when the MLX accelerator bundle is included).
- The Canopy CLI, logged in (
canopy login). - To be an administrator of the team the Mac will join.
canopy forest join # add --no-auto-placement to keep it to steps that name this MacThe command checks the machine, then:
- mints a single-use enrollment token for your team (it is held in memory and handed to the installer over a local socket; it never appears on a command line, in the environment or in logs),
- downloads the signed release and verifies its Ed25519 signature and sha256 digest before anything runs,
- shows one summary of what will be installed and asks once (
--yesskips only that question), - asks macOS for your administrator password once, to install a small root helper,
- installs and starts the agent through the helper, then runs functional checks: enrolled, heartbeat, a hello job, Metal visible and an MLX smoke job.
It prints one line per step and a final summary, and reports success only when every check
passed. If a step fails it names the step and the fix; the Mac is left in a runnable state and
running canopy forest join again continues from there.
If you belong to several teams the command asks which one on a terminal; in scripts pass
--team <id>. The Grove is named after the Mac’s hostname plus a short random suffix (names are unique across Canopy) unless you pass --name. Exec and logs sessions to a Mac node are not available yet, so join shows the tunnel check as skipped.
What gets installed
Section titled “What gets installed”- the helper daemon
pm.canopy.forest-helper(root, reachable only through a local Unix socket and limited to a fixed set of operations), - the agent daemon
pm.canopy.forest-agent, running as the service user_canopyforest, - a deny-by-default inbound firewall rule,
- optionally the Metal helper and the MLX bundle (skip them with
--no-accelerators) and the WireGuard helper binary when--ingressis requested. Mesh-device setup is currently skipped, as noted above.
The release is signed by Canopy and the binaries are ad-hoc code signed; nothing is notarized by Apple, and nothing is downloaded through a browser, so Gatekeeper never prompts. Later updates run through the helper and do not ask for a password again.
The Metal helper and the GPU memory
Section titled “The Metal helper and the GPU memory”An Apple GPU shares the Mac’s memory, and Metal lets one process use less than all of it. A release that carries the
metal-helper makes the agent report the figure Metal itself gives, so Canopy refuses a step that asks for more instead of
letting it fail inside the framework. A Mac that joined before a release carried the helper gets it with the next
canopy forest update, which also adds the helper to the agent’s LaunchDaemon; if the new version does not come up healthy
the update puts the old LaunchDaemon back. canopy forest status and arborist accelerator-inventory show the figure once
it is known.
Staff build the helper on an Apple silicon Mac with forest/scripts/build-metal-helper.sh and attach it with
forest/scripts/build-native-release.sh --metal-helper dist/metal-helper/metal-helper.
Day to day
Section titled “Day to day”canopy forest status # the team's native Groves and this Maccanopy forest groves list # the team's Macs and whether automatic placement is on for eachcanopy forest groves update my-mac --auto-placement on # let steps that name no machine run on itcanopy forest groves update my-mac --pools cortex-gpu # put it in a pool a step can ask for (native.pool)canopy forest verify # re-run the functional checkscanopy forest doctor # redacted diagnostic bundle (share it with support)canopy forest update --check # is a newer signed release available?canopy forest update # stage, switch, health-check, roll back on failurecanopy forest leave # revoke the Grove in Canopy, then uninstall the agentcanopy forest leave --purge # also remove the identity, the service user and the helperleave revokes the Grove in Canopy first. If removal on the Mac stops halfway, the Grove is
already revoked and running the command again finishes the job.
Exit codes and automation
Section titled “Exit codes and automation”--json prints one JSON object per step and a final result object. Exit code 0 means success,
1 a failed step, and 2 a machine or invocation that cannot proceed (not an Apple silicon Mac,
macOS older than 14, not enough disk, no terminal and no --yes, several teams and no --team).
See the CLI reference.