Skip to content

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.

  • 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 Mac

The command checks the machine, then:

  1. 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),
  2. downloads the signed release and verifies its Ed25519 signature and sha256 digest before anything runs,
  3. shows one summary of what will be installed and asks once (--yes skips only that question),
  4. asks macOS for your administrator password once, to install a small root helper,
  5. 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.

  • 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 --ingress is 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.

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.

canopy forest status # the team's native Groves and this Mac
canopy forest groves list # the team's Macs and whether automatic placement is on for each
canopy forest groves update my-mac --auto-placement on # let steps that name no machine run on it
canopy 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 checks
canopy 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 failure
canopy forest leave # revoke the Grove in Canopy, then uninstall the agent
canopy forest leave --purge # also remove the identity, the service user and the helper

leave 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.

--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.