Self-Install auspex on macOS

This guide is for individual engineers installing the Span agent (auspex) on their own Mac, without an MDM. It installs entirely in your user account — no admin password, no sudo, and no install script required.

If your Mac is managed by your company's MDM (Mosyle, Jamf, Intune, etc.), you do not need this guide — auspex is deployed for you centrally. This is only for self-service / individual installs.

Before you start

• A Mac running macOS 13 or later
• Your Span auth token (provided by your Span administrator)
  • NOTE: this needs to be the global org auth token, not a PAT (see how your admin gets the token)
• Your work email

No admin access is needed — everything installs under your home directory (~/.auspex).

Step 1: Download the agent

Open the Terminal app. Pick any folder to work in — we'll call it <WORKDIR> (e.g. ~/Downloads). This command detects your Mac's architecture (Apple Silicon or Intel) and downloads the matching package:

cd <WORKDIR>
ARCH=$([ "$(uname -m)" = "arm64" ] && echo arm64 || echo amd64)
curl -fLO "https://auspex.span.app/releases/v0.1.0/darwin/auspex_0.1.0_darwin_${ARCH}.tar.gz"

Step 2: Install

In the same Terminal window, replace <TOKEN> and <EMAIL> with your values and run:

tar -xzf "auspex_0.1.0_darwin_${ARCH}.tar.gz"
./auspex install --service --token <TOKEN> --email <EMAIL>

What this does, all within your user account:

• places the auspex binary on your PATH under ~/.auspex,
• wires the capture hooks into your AI coding tools (Claude Code, Cursor, Codex, …),
• saves your token and work email to a private (0600) identity file only you can read,
• registers a per-user login agent (--service) so the daemon starts now and at every login.

✅ Done when the installer prints auspex installed: with your binary path and identity: user tier provisioned. If it warns that the binary's directory isn't on your PATH, either follow the printed hint or open a new Terminal window before the next step.

Step 3: Verify

auspex status
auspex auth show

• auspex status should report the daemon running with install mode: user.
• auspex auth show should show your work email and a masked token.

Then use Claude Code or Cursor briefly and confirm your traces appear in the Span dashboard (ask your Span rep to enable the feature for your org if you don't see anything yet).

Step 4: Clean up (optional)

Once the health check passes, the downloaded archive is no longer needed (from <WORKDIR>):

rm <WORKDIR>/auspex_0.1.0_darwin_*.tar.gz

Verify anytime

auspex status

Uninstall

auspex uninstall

This removes the agent, its login service, and the hooks auspex wrote. Your own custom hooks in Cursor and Claude Code are preserved.

(Optional) File access & the background-item notice

On a managed (MDM) fleet, a configuration profile pre-grants auspex Full Disk Access and silences the first-run background-item notice. That profile is an MDM-only mechanism (it requires a supervised device), so there is nothing equivalent to install on a self-install Mac — and in most cases you don't need to do anything. The two effects, and how to handle them yourself if needed:

• The "background item" notice. The first time auspex's login agent registers, macOS may show a one-time "auspex can run in the background" notification. It's benign — no action needed. You can review it any time under System Settings → General → Login Items & Extensions.

• File access — only if you actually get prompted. auspex reads your edited files from your project's git working tree. If your repositories live under a TCC-protected folder (Documents, Desktop, or Downloads), macOS may show "'auspex' would like to access files in your Documents folder." You have two easy options:

  • Click Allow on the prompt, or
  • Grant it once yourself: System Settings → Privacy & Security → Full Disk Access → ＋, press ⌘⇧G, enter ~/.auspex/bin/auspex, add it, and turn the toggle on.

  If you keep your repos under a non-protected path (e.g. ~/dev, ~/src, ~/code), you'll never see this and there's nothing to do. (A bare command-line tool can be re-prompted by macOS even after clicking Allow; adding it to Full Disk Access as above is the durable fix.)

Troubleshooting

• auspex: command not found — the binary's directory isn't on your PATH yet. Open a new Terminal window, or run it by full path: ~/.auspex/bin/auspex status.
• this device is centrally managed on install — your Mac already has a managed (MDM) auspex install, which outranks a user install. Nothing to do; you're already covered.
• --token ... is required / auth errors — re-run Step 2 with the org auth token from your Span administrator (a global token, not a PAT).
• macOS asks to allow access to your Documents/Desktop folder — this can appear if your repositories live under a TCC-protected folder (Documents, Desktop, or Downloads). Click Allow. (Most engineers keep repos under a non-protected path like ~/dev or ~/src and never see it. On MDM-managed Macs this is pre-approved centrally; on a self-install you approve it yourself.)
• No traces in the dashboard — this is expected on a fresh install until you've used a coding tool and your org has the feature enabled. Use Claude Code or Cursor briefly, then re-check auspex status. If it persists, contact the Span team.

If you are stuck on an issue not listed here, please share the full Terminal output (and the output of auspex status) with the Span team.