auspex managed settings
Last updated: November 19, 2026
On a managed device, your organization's settings live in managed.yaml, which your MDM deploys. It takes the same settings as an engineer's own config.yaml, with the same meaning; auspex settings lists them. This article covers what is specific to the managed file: where it lives, how it outranks an engineer's settings, how to deploy it, and the per-device commands for the tool list.
Where it lives
OS | Path |
|---|---|
macOS |
|
Windows |
|
The package creates a managed.yaml with no settings in it when none exists, and keeps the file on every later install and upgrade. Its presence is what makes a device managed.
How it combines with an engineer's settings
A setting in managed.yaml overrides auspex's default, but an engineer's own config.yaml still wins over it. To make a setting final, list it under locked:; a locked setting wins over the engineer's file too:
capture:
tools: [claude-code, cursor]
locked:
- capture.tools
A lock needs the setting to be in the file. To lock the default tool list, write capture.tools: [default] with the lock.
The tool list works a little differently: an engineer's config.yaml never changes a managed device's tools, locked or not. The lock on capture.tools instead stops the per-device commands below from adding tools.
Deploy it on a new deployment
Deliver managed.yaml before the package installs, so the device runs with your settings from its first run. Deploy the script the same way, and at the same time, as the identity script in your MDM guide. It only creates the file, so re-running it never changes a device that already has one, and it can follow the identity lines in a combined script. Replace the settings between the markers with yours.
macOS, run as root:
#!/bin/bash
set -euo pipefail
CONFIG_DIR="/Library/Application Support/auspex"
CONFIG_FILE="${CONFIG_DIR}/managed.yaml"
if [ -e "${CONFIG_FILE}" ]; then
echo "managed.yaml already present; left unchanged"
else
mkdir -p "${CONFIG_DIR}"
# --- your settings ---
printf 'capture:\n tools: [claude-code, cursor]\n' > "${CONFIG_FILE}"
# ---------------------
chown root:wheel "${CONFIG_DIR}" "${CONFIG_FILE}"
chmod 755 "${CONFIG_DIR}"
chmod 644 "${CONFIG_FILE}"
echo "Success: managed.yaml written"
fi
Windows, run as System:
$ErrorActionPreference = 'Stop'
$Dir = 'C:\ProgramData\auspex'
$File = Join-Path $Dir 'managed.yaml'
if (Test-Path -LiteralPath $File) {
Write-Output 'managed.yaml already present; left unchanged'
} else {
New-Item -ItemType Directory -Force $Dir | Out-Null
# --- your settings ---
$yaml = "capture:`n tools: [claude-code, cursor]`n"
# ---------------------
# UTF-8 without a BOM, as for identity.json.
[IO.File]::WriteAllText($File, $yaml, (New-Object System.Text.UTF8Encoding $false))
}
The package checks the file before it sets anything up, on every install and upgrade. On macOS the file must be owned by root, writable only by root and readable by everyone, as the script leaves it. On Windows only System and Administrators may be able to change it, as is true of a file System writes. If the file doesn't load or fails that check, the install fails with the reason in its log, so your MDM reports the device.
Change it on a fleet that already runs auspex
The package never replaces an existing managed.yaml, so change it with auspex managed apply (auspex v0.14.0 and later). Keep your whole policy in one script and push it to every device: apply replaces the device's file with it. Pushing the same script again changes nothing, so you can run it on a schedule.
macOS, run as root:
#!/bin/bash
set -euo pipefail
/usr/local/bin/auspex managed apply - <<'EOF'
# --- your settings ---
capture:
tools: [claude-code, cursor]
locked:
- capture.tools
# ---------------------
EOF
Windows, run as System:
$ErrorActionPreference = 'Stop'
$File = Join-Path $env:TEMP "auspex-managed-$([guid]::NewGuid()).yaml"
# --- your settings ---
$yaml = "capture:`n tools: [claude-code, cursor]`nlocked:`n - capture.tools`n"
# ---------------------
# UTF-8 without a BOM: apply refuses a file that starts with one.
[IO.File]::WriteAllText($File, $yaml, (New-Object System.Text.UTF8Encoding $false))
& 'C:\Program Files\auspex\bin\auspex.exe' managed apply $File
$code = $LASTEXITCODE
Remove-Item -LiteralPath $File -ErrorAction SilentlyContinue
exit $code
It checks the file first. A file auspex can't load, such as a mistyped value or an unknown setting under
locked:, is refused, and the device's file is left as it was. The script then exits with an error, so your MDM reports the device.An unknown setting only warns. A setting this auspex doesn't know, or no longer uses, prints a warning and the rest of the file still lands, so devices on an older or newer release take the same file. To catch a misspelled setting before you push, run
auspex managed validate policy.yamlon any Mac or PC with auspex; it refuses unknown settings too.The file lands as you wrote it, comments included, and keeps the protection the package gives it.
The change applies within about 90 seconds.
applyupdates the device's hooks straight away, and each engineer's auspex restarts itself onto the new settings. If nobody is logged in to a Mac, the next login applies it.applynever createsmanaged.yaml: only the package makes a device managed.
Add or remove a tool on some devices
To change the tool list on a few devices without touching managed.yaml, run these on them as root on macOS, or from an elevated prompt on Windows. From your MDM, run them as a script on the devices you choose, or publish them as a self-service item.
macOS:
/usr/local/bin/auspex hooks install --system --tool opencode
/usr/local/bin/auspex hooks uninstall --system --tool opencode
Windows:
& 'C:\Program Files\auspex\bin\auspex.exe' hooks install --system --tool opencode
& 'C:\Program Files\auspex\bin\auspex.exe' hooks uninstall --system --tool opencode
Each command adds or deletes one file in managed.d, the folder beside managed.yaml, and updates the device's hooks. A file there can only add tools. The commands never edit managed.yaml, and package upgrades keep the files.
hooks install --system --toolis refused whenmanaged.yamllockscapture.tools, and files already inmanaged.dare then ignored.hooks uninstall --system --toolexits with an error whenmanaged.yamlstill lists the tool, and names it, so your MDM reports the device.
Check a device
auspex managed show prints the device's managed.yaml and whether auspex loads it, and exits with an error if it doesn't. If a changed file doesn't load, auspex keeps its current settings, and auspex status reports the problem under managed_config.
auspex hooks status lists each tool and where it comes from: the default tools, managed.yaml, or a file in managed.d. It also lists any file in managed.d that auspex ignores, and why, such as the lock or a file an admin didn't create.