Agent updates

The mngd agent auto-updates. Once a new version is published on the server, every agent in an org picks it up on its next checkin (at most ~60 minutes) and installs it silently via its privileged helper. Admins don’t push new pkgs through MDM, and end users don’t see a prompt.

How it works

1. On every periodic checkin the agent fetches GET /api/v1/agent/latest — a tiny JSON manifest of the most recent published release.
2. If server.version > local.version, the agent downloads the pkg to /tmp, verifies the SHA-256 against the manifest, and asks the privileged helper to run /usr/sbin/installer -pkg <path> -target /.
3. The old process exits; launchd relaunches against the freshly installed binary.

If any step fails — manifest endpoint 404, bad sha, download failure, helper unreachable — the agent logs a warning and stays on the current version. The self-update path can’t brick the agent.

Publishing a new release

Today this is a raw SQL insert against agent_releases (a superadmin UI is on the roadmap). On your mngd server:

INSERT INTO agent_releases
    (version, download_url, sha256, release_notes)
VALUES
    ('1.0.1',
     'https://cdn.mngd.app/agent/mngd-agent-1.0.1.pkg',
     '<sha256 of the pkg, lowercase hex>',
     'First post-beta release — see changelog for details.');

Required fields:

Column	Notes
version	Dotted numeric (1.0.1). Compared left-to-right per part.
download_url	Public URL — the agent hits it without credentials.
sha256	Lowercase hex SHA-256 of the pkg. Verified before install.
release_notes	Optional. Shown in a future admin UI.
min_required_version	Optional. When set, agents below this version block checkin until they update.
active	Defaults to true. Flip to false to yank a bad release.

Pulling a bad release

Something go wrong in the first hour after publishing? Flip active:

UPDATE agent_releases SET active = false WHERE version = '1.0.1';

Every agent that hits /agent/latest now sees the previous active release (or a 404 if there isn’t one), and stops trying to upgrade. Agents already running 1.0.1 stay on 1.0.1 — they don’t downgrade themselves, because that path would be dangerous if a release broke the auto-updater itself.

To recover devices stuck on a bad release you’d publish a new version (e.g. 1.0.2) that rolls back whatever 1.0.1 broke.

Forcing devices forward

For a security-critical fix where you can’t wait for the natural checkin cadence, set min_required_version:

INSERT INTO agent_releases
    (version, download_url, sha256, min_required_version)
VALUES ('1.0.2', '…', '…', '1.0.2');

Agents at or below that floor refuse to keep checking in until they self-update. Use sparingly — it’s a load event and a bad manifest here can lock every device out of your org.

What the end user sees

Nothing, in the default configuration. The install runs silently via the privileged helper (already deployed in /Library/Privileged HelperTools/ by the pkg postinstall). The mngd menubar icon briefly disappears during launchd relaunch and comes back on the new version.

A future release will add an in-app “update available” notification so users can defer the install window if they’re in the middle of something; for now it’s silent to match how MDM patching usually feels.

Troubleshooting

• Agent seems stuck on an old version. Check the Mac’s ~/Library /Logs/mngd/mngd.log (or /var/log/mngd.log for the helper side) for SelfUpdate: lines. You’ll see the version comparison, the download URL, and either install complete or the exit code / error from the failing step.
• Privileged helper not reachable. Run sudo launchctl kickstart -k system/com.mngd.helper. If that doesn’t recover it, reinstall the pkg manually.
• SHA-256 mismatch. The pkg on the CDN doesn’t match the manifest. Re-extract the correct hash from the pkg you actually uploaded and update the agent_releases row.