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

/Library/Application Support/auspex/managed.yaml

Windows

C:\ProgramData\auspex\managed.yaml

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.yaml on 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. apply updates 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.

  • apply never creates managed.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 --tool is refused when managed.yaml locks capture.tools, and files already in managed.d are then ignored.

  • hooks uninstall --system --tool exits with an error when managed.yaml still 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.