macOS

Apple Silicon and Intel. What each method reads is in the platform table.

macOS is listed as not yet verified on hardware for the first release; see the support table in the README.

With the agent#

The short way, with a PIN. In the hub, open Add a host, choose macOS, and note the six-digit PIN. Download the file for your CPU (below), then run chmod +x yarrix-darwin-arm64 && sudo ./yarrix-darwin-arm64 agent join. It finds the hub on the network, asks for the PIN, writes /etc/yarrix/agent.yaml, installs the binary and the LaunchDaemon, and loads it. Details and flags: AGENT.md. The steps below are the same thing done by hand.

The wizard can do the steps below for you over SSH (Install it for me, which uses sudo for /usr/local/bin, /etc/yarrix and the LaunchDaemon; see install.md). The by-hand steps below always work.

The agent is the same single binary as on Linux. Download the file for your CPU from your hub's /download/agent/ (yarrix-darwin-arm64 for Apple Silicon, yarrix-darwin-x64 for Intel) and check it against its .sha256.

1. On the hub: yarrix-hub enroll create --host mac-1.

2. Try it by hand first: chmod +x yarrix-darwin-arm64 && ./yarrix-darwin-arm64 agent --hub https://yarrix.example.net --enroll-token <token>. The host shows up in Systems within seconds; stop it with Ctrl-C.

3. Run it at boot as a LaunchDaemon: install the binary as /usr/local/bin/yarrix, copy deploy/agent.example.yaml to /etc/yarrix/agent.yaml (set hub: and enroll_token_file:), copy deploy/launchd/io.yarrix.agent.plist to /Library/LaunchDaemons/, and load it:

   sudo launchctl bootstrap system /Library/LaunchDaemons/io.yarrix.agent.plist
   

   The plist keeps the agent running (restart after 5 seconds), keeps its state in /var/lib/yarrix and logs to /var/log/yarrix-agent.log. Delete the token file once the host has appeared.

The agent reads GPU utilization on Apple Silicon without root (see below).

Agentless over SSH#

1. Enable Remote Login in System Settings, General, Sharing.
2. Create a standard (non-admin) user for it, for example monitor, and put the hub's public key in that user's ~/.ssh/authorized_keys (file mode 600, folder mode 700). A standard user can read every base metric.
3. Host file:

host: atlas
os: macos            # or auto
collect: { method: ssh }
ssh: { target: monitor@atlas.example.internal }

What you get with no extra tools: CPU (two top samples), load, memory (counted like Activity Monitor), swap, uptime, volumes, disk I/O (I/O Registry, bytes per physical disk), network, battery and power source (as facts).

df shows the user's data on /System/Volumes/Data. The sealed system volume at /, APFS helper volumes and developer disk images are left out so they never raise a false "disk full".

GPU on Apple Silicon#

Question: can the agent read GPU utilization on Apple Silicon without root?

Tried on an arm64 Mac (macOS 27.2) as an ordinary user (uid 501):

• IOReport (/usr/lib/libIOReport.dylib, private). dlopen works. IOReportCopyChannelsInGroup("GPU Stats"), a subscription, two samples 0.5 s apart and a delta returned over 100 channels with no root. The GPU is exposed as residency per performance state (GPUPH: OFF, P1 to P15) plus counters, not as a busy percentage. Turning residency into "percent busy" needs knowledge of Apple's private state naming, and the API is undocumented and unversioned.
• I/O Registry. Every IOAccelerator publishes PerformanceStatistics with Device Utilization % (also Renderer and Tiler). ioreg -r -c IOAccelerator -d 1 -w0 reads it as an ordinary user and returned 53 to 60 while the GPU was in use. This is a documented registry property, needs no private library and no root.

Result: GPU utilization on Apple Silicon is readable without root. The agent uses the I/O Registry counter (collect/gpu.rs). IOReport stays the route if GPU power or frequency is wanted later; it was not needed for utilization. Not done: a side-by-side of the counter against Activity Monitor under a controlled load. If a Mac reports no Device Utilization %, capabilities.gpu is unknown with a reason and the host's GPU field shows unknown.

Gatekeeper and unsigned binaries#

The macOS binaries (yarrix-darwin-arm64, yarrix-darwin-x64, and the hub executables for macOS) are not signed with an Apple Developer ID and not notarized. Gatekeeper checks that on files that carry the quarantine flag, which is set on files downloaded with a browser (and by some chat and mail apps). Opening such a file shows "cannot be opened because the developer cannot be verified", or the file is moved to the Bin.

• Downloaded with curl (or from your hub's /download/agent/ with curl, or by the wizard's Install it for me): the file has no quarantine flag and runs.

• Downloaded in a browser: remove the flag once, after verifying the download, then run it:

  xattr -d com.apple.quarantine ./yarrix-darwin-arm64
  

  Or, in System Settings, Privacy & Security, scroll to the blocked item and choose Allow Anyway, then run it again and confirm.

• A binary started by launchd as the LaunchDaemon above is not asked about; the flag matters when you start it by hand.

The checksum and minisign signature in verify-release.md are how you check these files are the project's. Notarization is not done yet. The Gatekeeper behaviour above is from Apple's documentation; the project has not recorded a walkthrough of it.

Known limits#

• Temperature needs root-level tooling and is unknown.
• Services and containers need the agent.
• The hub container image carries an SSH client, so agentless collection works from it (Linux page).