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/latest/darwin/auspex_darwin_${ARCH}.tar.gz"

Step 2: Install

Unpack the archive, then install. So your token never lands in your shell history or the process list (ps), paste it into an environment variable with a silent prompt — nothing is echoed as you paste — and let the installer read it from there. Replace <EMAIL> with your work email:

tar -xzf "auspex_darwin_${ARCH}.tar.gz"
printf 'Paste your Span token, then press Enter: '; read -rs AUSPEX_CLOUD_TOKEN; echo; export AUSPEX_CLOUD_TOKEN
./auspex install --service --email <EMAIL>

install reads the token from AUSPEX_CLOUD_TOKEN, writes it to a private (0600) identity file only you can read, and the daemon reads it from that file thereafter — not from your shell environment.

Other ways to supply the token.

• From a file (e.g. exported by a secrets manager) — the secret stays out of the process list: ./auspex install --service --token-file ~/span-token.txt --email <EMAIL>.
• Inline — ./auspex install --service --token <TOKEN> --email <EMAIL> also works, but is discouraged: the token is then visible in your shell history and to ps. auspex prefers --token-file or AUSPEX_CLOUD_TOKEN for this reason.

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_darwin_*.tar.gz

(Optional) Pin and verify an exact build

The download in Step 1 uses the version-less latest alias — the simplest path, and it is unchanged. If you'd like a reproducible, tamper-evident install (recommended for security-conscious setups), you can pin an exact release and verify its bytes against auspex's cryptographic signature before installing.

Each release publishes a cosign-signed manifest.json that binds the version to the exact SHA-256 of every artifact, and every artifact is also stored at a global, content-addressed path (https://auspex.span.app/blobs/sha256/<digest>) — so a digest is a version-free pin that always resolves to the same bytes. This needs two small tools (brew install cosign jq).

cd <WORKDIR>
V=v0.2.0                                   # the exact release you want (ask your admin or see the changelog)
ARCH=$([ "$(uname -m)" = "arm64" ] && echo arm64 || echo amd64)

# 1. Fetch the signed version→digest manifest and verify it came from auspex's release pipeline:
curl -fsSLO "https://auspex.span.app/releases/${V}/manifest.json"
curl -fsSLO "https://auspex.span.app/releases/${V}/manifest.json.cosign.bundle"
cosign verify-blob \
  --bundle manifest.json.cosign.bundle \
  --certificate-identity-regexp '^https://github\.com/(?i:attuned-corp)/auspex/\.github/workflows/release\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  manifest.json

# 2. Confirm the manifest is for the version you asked for, then read the macOS archive's signed digest:
test "$(jq -r '.annotations["org.opencontainers.image.version"]' manifest.json)" = "$V"
DIGEST=$(jq -r --arg arch "$ARCH" \
  '.manifests[] | select(.mediaType=="application/gzip" and .platform.os=="darwin" and .platform.architecture==$arch) | .digest' manifest.json)

# 3. Fetch the archive BY DIGEST (version-free) and confirm its bytes match the signed digest:
D=${DIGEST#sha256:}
curl -fL -o "auspex_darwin_${ARCH}.tar.gz" "https://auspex.span.app/blobs/sha256/${D}"
echo "${D}  auspex_darwin_${ARCH}.tar.gz" | shasum -a 256 -c -

If the final check prints auspex_darwin_${ARCH}.tar.gz: OK, the archive is verified — continue from Step 2 (tar -xzf …). A failed cosign verify-blob or a checksum mismatch means do not install — contact the Span team.

The sha256:<digest> you verified once is a durable pin: https://auspex.span.app/blobs/sha256/<digest> returns those exact bytes regardless of version, so you can record it in a setup script or lockfile.

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.
• provisioning was requested but no token was supplied / auth errors — AUSPEX_CLOUD_TOKEN wasn't set in the shell that ran install (a new Terminal window doesn't inherit it). Re-run the silent-prompt line and install in the same window, or pass --token-file <path>. Use the org auth token from your Span administrator (a global token, not a PAT), and confirm with auspex auth show.
• 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.