Self-Install auspex on Windows

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

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

Before you start

• Windows 10 (build 1809 or later) or Windows 11
• 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 administrator access is needed — everything installs under your user profile (%USERPROFILE%\.auspex). In fact the installer refuses to run elevated: a per-user install from an admin prompt would place files your own account can't manage.

Which build do I need — amd64 or arm64?

Almost certainly amd64. Every Intel and AMD PC uses it, which is the overwhelming majority of corporate fleets.

Pick arm64 only for a Windows on Arm device — in practice a Snapdragon-based Copilot+ PC (Surface Pro 11, Surface Laptop 7, Dell XPS 13 9345, Lenovo ThinkPad T14s Gen 6, and similar), or a Windows VM on an Apple Silicon Mac (Parallels, VMware Fusion, UTM).

If you're not sure, ask PowerShell:

$env:PROCESSOR_ARCHITECTURE

AMD64 → use the amd64 build. ARM64 → use the arm64 build.

Fleet admins: don't guess for the whole estate. Windows on Arm is still a small slice of most fleets, but it is not zero, and an amd64 .msi will not install on an Arm device. See Checking architecture across a fleet for a query you can run from your MDM.

Step 1: Download the agent

Open PowerShell (the normal one — not "Run as administrator"). Pick any folder to work in — we'll call it <WORKDIR> (e.g. C:\auspex). This detects your PC's architecture and downloads the matching executable:

cd <WORKDIR>
$Arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'amd64' }
$Exe  = "auspex_windows_$Arch.exe"
Invoke-WebRequest -Uri "https://auspex.span.app/releases/latest/windows/$Arch/auspex.exe" -OutFile $Exe
Unblock-File $Exe

Unblock-File clears the "downloaded from the internet" mark so Windows doesn't block the executable.

Step 2: Install

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

.\$Exe install --service --token <TOKEN> --email <EMAIL>

What this does, all within your user account:

• places the auspex binary under %USERPROFILE%\.auspex\bin,
• wires the capture hooks into your AI coding tools (Claude Code, Cursor, Codex, GitHub Copilot, VS Code),
• saves your token and work email to a private identity file only you can read,
• registers a per-user logon task (--service) so the daemon starts now and at every sign-in.

The daemon runs invisibly — you should not see a console window. If one appears and stays open, see Troubleshooting.

✅ Done when the installer prints auspex installed: with your binary path and identity: user tier provisioned.

Step 3: Verify

& "$env:USERPROFILE\.auspex\bin\auspex.exe" status
& "$env:USERPROFILE\.auspex\bin\auspex.exe" auth show

• status should report the daemon running with install mode: user.
• 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).

auspex is not on your PATH after a self-install. A managed (.msi) install adds it for every user on the device; a per-user install deliberately does not, because adding to PATH is a machine-wide change. Use the full path as above, or add %USERPROFILE%\.auspex\bin to your own user PATH under Settings → System → About → Advanced system settings → Environment Variables.

Step 4: Clean up (optional)

Once the health check passes, the downloaded executable is no longer needed — the installer placed its own copy under %USERPROFILE%\.auspex\bin:

Remove-Item "<WORKDIR>\$Exe"

(Optional) Pin and verify an exact build

The download in Step 1 uses the version-less latest alias — the simplest path. If you'd like a reproducible, tamper-evident install, you can pin an exact release and verify its bytes before installing.

Each release publishes a cosign-signed manifest.json binding the version to the exact SHA-256 of every artifact, and every artifact is also stored at a 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 cosign on your PATH.

cd <WORKDIR>
$V    = 'v0.2.0'                                    # the exact release you want (ask your admin or see the changelog)
$Arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'amd64' }

# 1. Fetch the signed version→digest manifest and verify it came from auspex's release pipeline:
Invoke-WebRequest "https://auspex.span.app/releases/$V/manifest.json" -OutFile manifest.json
Invoke-WebRequest "https://auspex.span.app/releases/$V/manifest.json.cosign.bundle" -OutFile 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 Windows binary's signed digest:
$m = Get-Content manifest.json | ConvertFrom-Json
if ($m.annotations.'org.opencontainers.image.version' -ne $V) { throw "manifest is not $V" }
$digest = ($m.manifests | Where-Object { $_.platform.os -eq 'windows' -and $_.platform.architecture -eq $Arch -and $_.mediaType -eq 'application/octet-stream' }).digest
$d = $digest -replace '^sha256:',''

# 3. Fetch the binary BY DIGEST (version-free) and confirm its bytes match:
Invoke-WebRequest "https://auspex.span.app/blobs/sha256/$d" -OutFile "auspex_windows_$Arch.exe"
if ((Get-FileHash "auspex_windows_$Arch.exe" -Algorithm SHA256).Hash.ToLower() -ne $d) { throw 'DIGEST MISMATCH — do not install' }
'verified'

If it prints verified, continue from Step 2 (run the file you just downloaded). A failed cosign verify-blob or a digest mismatch means do not install — contact the Span team.

Only the standalone .exe is indexed in the signed manifest. The .msi used for managed installs is signed with a Windows code-signing certificate instead and carries its own .sha256 sidecar beside it on the download host.

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

& "$env:USERPROFILE\.auspex\bin\auspex.exe" status

Uninstall

& "$env:USERPROFILE\.auspex\bin\auspex.exe" uninstall

This removes the agent, its logon task, and the hooks auspex wrote. Your own custom hooks in Cursor and Claude Code are preserved, and your captured data and config under %USERPROFILE%\.auspex are kept. To remove those too:

Remove-Item -Recurse -Force "$env:USERPROFILE\.auspex"

Replacing the legacy coding-hooks agent

If this PC still has Span's earlier coding-hooks agent, remove it once auspex is healthy — running both captures every event twice. See Retiring coding-hooks, which includes a check-then-uninstall script you can run yourself or push from your MDM.

Troubleshooting

• auspex : The term ... is not recognized — you're typing a bare auspex, which a self-install doesn't put on your PATH. Use the full path: & "$env:USERPROFILE\.auspex\bin\auspex.exe" status.
• refusing to run elevated — you opened PowerShell as administrator. Close it and use a normal PowerShell window; auspex installs per-user by design.
• this device is centrally managed — your PC already has a managed (MDM) auspex install, which outranks a user install. Nothing to do; you're already covered.
• A console window stays open — the daemon should run invisibly. If a window titled with the auspex path persists, your install predates the fix; re-run install --service to re-register the logon task with the current launcher.
• Windows SmartScreen warns about the download — the standalone .exe is published with a checksum rather than a code-signing certificate, so SmartScreen may show "Windows protected your PC" on first run. Verify the download with the pin-and-verify steps above, then choose More info → Run anyway. The .msi used for managed installs is signed; if your organization prefers a signed artifact, ask your admin to deploy that instead.
• token malformed or uploads not arriving — if you saved your token to a file with PowerShell, it may be UTF-16 or carry a byte-order mark. Re-run with --token <TOKEN> inline, or write the file as UTF-8 without a BOM.
• No traces in the dashboard — 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 status.

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