Upgrading auspex

Last updated: November 11, 2026

Most auspex releases need nothing beyond deploying the new version the way you installed it. This page lists only the releases that also need a manual step, newest first, and says who has to take it.

If you skip releases, apply every section between your current version and the one you're moving to, oldest first. Releases not listed here need no extra steps. Every release, listed or not, is in the release notes.

How to deploy a new version

Each install guide has its own upgrade section:

You installed with	How to upgrade
An MDM	Deploy the new package through your MDM, as in your MDM guide's Upgrading section. The guides are listed in Understanding Agent Traces
The self-install guide	`auspex upgrade` on v0.13.0 and later. Before v0.13.0, download the new release and install it again. See macOS, Windows or Linux
A `.deb`, `.rpm` or `.apk` package	Your package manager
A container image or Dev Container Feature	Rebuild the image with the new version
Cursor or Claude Code cloud agents	Nothing, unless you pinned `AUSPEX_VERSION`: each new environment installs the latest release

To confirm an upgrade on any device, run auspex status.

v0.13.0

v0.13.0 moves coding-tool hooks on macOS and Linux to auspex-capture, a small capture-only program that ships beside auspex. Three groups have a step to take:

Who	What to do	If you skip it
MDM admins on macOS	Give `auspex-capture` the same file access you give `auspex`, before the new package arrives	macOS may prompt users for, or block, reads of edited files under Documents, Desktop or Downloads
Self-installs on macOS or Linux	Reinstall from the whole release archive, then trust auspex's hooks again if you use Codex	Codex activity stops being captured until the hooks are trusted
Container images, devcontainers and CI images that pin by digest or download binaries by hand	Install `auspex-capture` beside `auspex`	Capture still works, but every event starts the full `auspex`, about twice as slowly

Windows needs no action, whether managed or self-installed. auspexw.exe keeps its name, location and signature, so hook settings and software allowlists that name it still apply.

MDM admins on macOS

From v0.13.0, /usr/local/bin/auspex-capture reads your developers' edited files, so it needs the same file access you already give auspex. Update whichever profile grants that access, and deploy it before the v0.13.0 package. What to update depends on the profile you use.

If you deploy Span's profile (auspex-background-items.mobileconfig), download it again from https://auspex.span.app/config/darwin/auspex-background-items.mobileconfig. Upload it in place of the old one and deploy it to the same devices. The new version adds an auspex-capture entry beside the existing auspex one. Your MDM guide's Step 2 has the upload steps.

If you deploy your own profile, review it and add an auspex-capture entry to every privacy service that has an auspex entry. Span's profile grants Full Disk Access, but auspex doesn't require it. Narrower rules, such as access to only the Documents, Desktop and Downloads folders, work as long as both programs get them. Copy each auspex entry and change two values:

Key	`auspex` (existing)	`auspex-capture` (add)
`Identifier`	`/usr/local/bin/auspex`	`/usr/local/bin/auspex-capture`
`IdentifierType`	`path`	`path`
`CodeRequirement`	`identifier "app.span.auspex" and anchor apple generic and certificate leaf[subject.OU] = KNH44SBYN4`	`identifier "app.span.auspex.capture" and anchor apple generic and certificate leaf[subject.OU] = KNH44SBYN4`

A code requirement with the wrong identifier never matches, and macOS gives no error. After the package installs, confirm the requirement on a device with codesign -dr - /usr/local/bin/auspex-capture. Background-item and notification rules need no change, because auspex-capture doesn't run in the background.

To check a device, open System Settings → Privacy & Security and find the section your profile grants, such as Full Disk Access or Files & Folders. auspex-capture should appear there beside auspex, marked "managed by your organization." If a user was prompted before the profile arrived, reset that service on the device with tccutil reset, for example tccutil reset SystemPolicyAllFiles for Full Disk Access.

Self-installs on macOS and Linux

Releases before v0.13.0 have no auspex upgrade command, so install v0.13.0 again as in Steps 1 and 2 of the macOS or Linux guide. Unpack the whole archive and run install from that folder, so auspex-capture sits beside auspex. If it doesn't, the installer warns hooks run the full auspex binary.

After upgrading:

If you use Codex, open Codex, run /hooks, and trust auspex's hooks once. Codex runs a changed hook only after you trust it, and v0.13.0 changes every auspex hook to run auspex-capture.
If you added auspex to Full Disk Access on macOS, add ~/.auspex/bin/auspex-capture too, as in the macOS guide's file access section. It now does the file read.

Container images, devcontainers and CI images

Whether you need to change anything depends on how your image gets auspex:

Your image gets auspex from	What to do
The Dev Container Feature with a `version`	Use Feature `0.6.0` or later. It installs `auspex-capture` for you
The Dev Container Feature with a `digest` pin	Use Feature `0.7.0` or later and replace `digest` with `manifestDigest`, the sha256 of the release's `manifest.json`. One pin covers both binaries. Or keep `digest` and add `captureDigest`
The auspex-distribution installer with `--digest`	Replace it with `--manifest-digest`, or add `--capture-digest` beside `--digest`
The auspex-distribution installer with `--version`, or no pin	Nothing. It installs `auspex-capture` for v0.13.0 and later
A Dockerfile that downloads `auspex` itself	Download `auspex-capture` into the same folder before `auspex install --supervised`, as in Step 1 of the container guide

The manifest digest pins every binary for every platform at once, so it's the simplest pin to maintain. See Pinning by digest for how to get it.

To check an image, run auspex status inside a container built from it. The capture_binary check passes with hooks run the capture binary. A warning means hooks still run the full auspex.

Going back to a release before v0.13.0

Releases before v0.13.0 don't recognize the new hook entries, so a plain downgrade captures every event twice. Remove the hooks with v0.13.0 or later first:

MDM on macOS: run sudo /usr/local/bin/auspex hooks uninstall --system, then deploy the older package.
Self-install: run auspex uninstall, then install the older release.
Container: run auspex uninstall in an existing container before installing the older release. A fresh image build needs nothing.