macOS (edge, dev only)

The ongrid-edge binary cross-compiles to darwin/amd64 and darwin/arm64. The Makefile builds both as part of make build-edge-all:

build-edge-darwin-amd64   → bin/darwin-amd64/ongrid-edge
build-edge-darwin-arm64   → bin/darwin-arm64/ongrid-edge

The binaries exist so engineers working on the agent can iterate on a Mac without spinning up a Linux VM. They are not a supported production target.

What works on macOS

• The agent process starts, reads ONGRID_EDGE_* env vars from your shell, and opens the geminio tunnel to the manager.
• Lifecycle RPCs work: the agent registers, sends heartbeats, accepts manager-initiated tool calls.
• The bash skill (cmdpolicy-gated) runs against the host: ls, ps, df, uname and a curated read-only set work as advertised.
• The embedded gopsutil collector backs host_info, get_host_load, get_host_processes. They return real numbers.
• WebSSH against 127.0.0.1:22 works (assuming you have enabled Remote Login in System Settings).

What does NOT work on macOS

Capability	Why
promtail logs plugin	Grafana does not publish a darwin promtail binary in their release tarballs. The make fetch-promtail step only fetches Linux.
node_exporter host-metrics plugin	Same upstream gap — node_exporter ships Linux-only releases.
process-exporter proc-metrics plugin	Same upstream gap.
otelcol-contrib traces plugin	Bundled only for Linux — keeps the release tarball under control.
The curl-pipe installer	deploy/install/edge/install.sh explicitly errors with only linux is supported by this installer; got: darwin.
systemd-style supervision	macOS uses launchd. No launchd plist ships in the release.
journald log source	macOS uses the unified log (os_log); the logs plugin would need a different reader even if promtail had a binary.
The ADR-024 staged-bundle upgrade hook	The hook is a Linux shell script wired into ExecStartPre=. There is no equivalent path.

What this means in practice: if you make build-edge-darwin-arm64 and run ./bin/darwin-arm64/ongrid-edge on your Mac, you will see your laptop appear in the Edges page of the manager UI, you can chat with the agent and have it run ls, ps, df, but the Logs page, the Monitor page's host panels, and the Traces page will all sit empty for that edge.

Running the agent on a Mac

# 1. cross-compile (or just `go build`, since you're already on darwin)
make build-edge-darwin-arm64

# 2. point at your manager
export ONGRID_EDGE_CLOUD_ADDR=ongrid.example.com:40012
export ONGRID_EDGE_ACCESS_KEY=<from manager UI: Edges → New>
export ONGRID_EDGE_SECRET_KEY=<from manager UI; shown once>

# 3. run it in the foreground
./bin/darwin-arm64/ongrid-edge

The agent logs to stderr. There is no /var/log/ongrid-edge/ because nothing creates it; if you want a logfile, redirect: ./ongrid-edge 2>&1 | tee ~/ongrid-edge.log.

launchd? Not yet

A launchd plist would give you start-on-login plus automatic restart. We have not shipped one because:

• The four plugins do not run on macOS anyway, so a supervised agent there gives you a subset of features that is hard to reason about.
• macOS hosts in production are extremely rare. We would rather not commit to a half-supported platform.

If you want one for your own development, here is a minimal example. Save as ~/Library/LaunchAgents/io.ongrid.edge.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>io.ongrid.edge</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/ongrid-edge</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>ONGRID_EDGE_CLOUD_ADDR</key><string>ongrid.example.com:40012</string>
    <key>ONGRID_EDGE_ACCESS_KEY</key><string>...</string>
    <key>ONGRID_EDGE_SECRET_KEY</key><string>...</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/ongrid-edge.out.log</string>
  <key>StandardErrorPath</key><string>/tmp/ongrid-edge.err.log</string>
</dict>
</plist>

Then launchctl load ~/Library/LaunchAgents/io.ongrid.edge.plist.

Codesigning / Gatekeeper

The agent is not codesigned. The first time you run it, macOS will refuse with "cannot be opened because the developer cannot be verified". Either:

• xattr -d com.apple.quarantine ./ongrid-edge to remove the quarantine flag, or
• Right-click → Open in Finder once, then it remembers your choice.

Building from source (go build ./cmd/ongrid-edge) on your own Mac avoids the quarantine flag entirely.

Should you use macOS in production?

No. Use a Linux box. The agent runs perfectly on a $5/month Linux VM; running it on a Mac mini works for a homelab but you lose the four plugins that supply 80% of the value Ongrid delivers (host metrics, logs, traces).

The dev-only path exists so we can dogfood the agent during development. It is not a deployment target.