Deploy the Dex Device Agent on macOS

In Dex

Dex only manages Macs when the Mac Device app is enabled in the App Store. Turn it on before enrolling devices — otherwise the agent connects but Dex has no tools or skills to act on it.

Open the App Store

Screenshot

In Dex

Sign in to the Dex management console, then go to Settings → Devices. Under Enrollment tokens, generate a new token (or reveal an existing one) — this is the value you'll substitute for {{ENROLLMENT_TOKEN}} in every method below. The pkg itself is tenant-agnostic; the token is always delivered separately.

Open the Dex console

Screenshot

Screenshot

Now in macOS

Install on one Mac — interactively in Finder with the configurator app, or headless from a terminal or SSH session.

In macOS

On a manually installed Mac there is no MDM to pre-grant TCC permissions, so macOS prompts the logged-in user the first time the agent needs each one — and some grants must be flipped by hand. Diagnostics and enrollment work without them; Computer Use features (screenshots, input control) and protected-path diagnostics need them.

In macOS

Reconfigure an enrolled Mac by running /Applications/Dex Device Agent/DexAgentConfigurator.app (it detects the existing enrollment and offers Reconfigure) or sudo … --configure. To upgrade, install the new pkg the same way — it upgrades in place, restarting the daemon while preserving enrollment and config.yaml. Uninstall with /Applications/Dex Device Agent/Uninstall Dex Device Agent.app, or from the terminal with the commands below.

sudo "/Library/Application Support/DexDeviceAgent/DexDeviceAgent" --uninstall
sudo rm -rf "/Library/Application Support/DexDeviceAgent" "/Library/Logs/DexDeviceAgent" \
    "/var/run/dexagent" "/var/log/dexdeviceagent.log" "/var/log/dexdeviceagent.err" \
    "/tmp/dexdeviceagent-helper.log" "/tmp/dexdeviceagent-helper.err"
sudo profiles remove -identifier com.sysaid.dexdeviceagent.config 2>/dev/null

In macOS

Use these deterministic checks after any method. The end-to-end confirmation is the device appearing in the Dex admin portal within a minute of enrollment.

Screenshot

# 1. Installed: binary present
test -x "/Library/Application Support/DexDeviceAgent/DexDeviceAgent" && echo installed

# 2. Daemon loaded and running
sudo launchctl list | grep com.sysaid.dexdeviceagent       # row with a PID = running

# 3. Configured: exit 0 iff an enrollment token or device secret exists
sudo "/Library/Application Support/DexDeviceAgent/DexDeviceAgent" --has-config && echo configured

# 4. Enrolled: after success the token is exchanged for a device_secret
#    in config.yaml (within ~30 s)
sudo grep -Eq 'device_secret:[[:space:]]*"?[^"[:space:]]' \
    "/Library/Application Support/DexDeviceAgent/config.yaml" && echo enrolled

# 5. If a profile delivers the token: confirm managed preferences landed
defaults read "/Library/Managed Preferences/com.sysaid.dexdeviceagent" 2>/dev/null

# 6. Recent logs, if anything above failed
sudo tail -50 /var/log/dexdeviceagent.log /var/log/dexdeviceagent.err