auspex: IT Admin User Guide for Rippling (Windows)

Last updated: August 27, 2026

This guide covers deploying the Span agent (auspex) to Windows devices with Rippling device management. For Macs, see the macOS guide.

What This Package Does

auspex captures AI coding activity (prompts, file edits, tool use) from supported IDEs — Claude Code, Cursor, Codex CLI, GitHub Copilot, and VS Code chat — and sends telemetry to Span's analytics backend. This data appears in your Span dashboard under AI Effectiveness.

On Windows the .msi installs machine-wide to C:\Program Files\auspex, registers a logon task so each engineer's agent starts when they sign in, and converges the device to the managed tier — capture is centrally governed and a user cannot install a competing copy over it.

Prerequisites

  • A Span account with access to integration settings.
  • Rippling device management enabled, with target Windows devices enrolled and assigned to a group.
  • Windows 10 (build 1809+) or Windows 11 with the Rippling agent installed.
  • Each engineer's work email present in their Rippling profile — it identifies the individual on their device.

Which architecture — amd64 or arm64?

Almost certainly amd64. Every Intel and AMD PC uses it, which is the overwhelming majority of corporate fleets. arm64 is needed only for Windows on Arm devices: Snapdragon-based Copilot+ PCs (Surface Pro 11, Surface Laptop 7, Dell XPS 13 9345, Lenovo ThinkPad T14s Gen 6 and similar), or Windows VMs on Apple Silicon Macs.

An amd64 .msi will not install on an Arm device, so don't assume a single build covers the fleet.

Checking architecture across a fleet

Rippling's device inventory reports processor details per device (Devices → All devices, then add the processor/architecture column and export). If your inventory doesn't distinguish clearly, push this one-liner as a script and collect the output:

"$env:COMPUTERNAME,$env:PROCESSOR_ARCHITECTURE"

AMD64 → the amd64 build. ARM64 → the arm64 build. If any Arm devices appear, create a second deployment with the arm64 .msi scoped to just those devices.

Deployment order (important)

  1. Identity script that writes identity.json — before or with the package.
  2. The package (line-of-business app, Required).

The package converges the device on install; if identity is already present, the agent starts reporting immediately rather than waiting for the next script cycle.

Step 1: Enable the Integration and Get Your Token (one-time)

This step is the same regardless of your MDM.

Head to the AI tool settings dashboard (https://span.app/_/settings/integrations) and under IDE & CLI AI Tool Integrations, enable the tools your engineers use. The token is shared org-wide and is required regardless of which IDEs you deploy for.

Step 2: Deliver the Identity File

The token is org-wide; the work email is per-device. Deliver both with a script that runs as System, so identity.json exists before (or with) the package.

In Rippling: Devices → Scripts → New script, target Windows, run as System. Attach it as a pre-install script on the software entry in Step 3 if Rippling offers that on your plan, so identity lands immediately before the package converges; otherwise schedule it recurring (daily is ample) so a device that enrols later still receives it.

$ErrorActionPreference = 'Stop'

# REQUIRED: paste your org token from Step 1
$Token = '<YOUR_TOKEN>'

# Replace with Rippling's variable for the assigned employee's work email
# (confirm the exact token in the Rippling script editor); resolves per-device.
$Email = '__RIPPLING_WORK_EMAIL_VARIABLE__'

if ([string]::IsNullOrWhiteSpace($Email) -or $Email -notmatch '^[^@\s]+@[^@\s]+\.[^@\s]+$') {
  Write-Error "Could not resolve a valid work email (got '$Email')."
  exit 1
}

$Dir = 'C:\ProgramData\auspex'
New-Item -ItemType Directory -Force $Dir | Out-Null

# UTF-8 WITHOUT a BOM. PowerShell's default encodings (UTF-16 from Out-File, or a BOM from
# Set-Content) would put stray bytes in the token, which auspex rejects as a malformed credential.
$json = '{{"token":"{0}","work_email":"{1}"}}' -f $Token, $Email
[IO.File]::WriteAllText((Join-Path $Dir 'identity.json'), $json, (New-Object System.Text.UTF8Encoding $false))
Write-Output "Success: identity.json written for $Email"

C:\ProgramData\auspex is the managed configuration tree. The .msi applies a restrictive ACL to it (SYSTEM and Administrators full control, Users read-only), so the token is not writable by the signed-in engineer.

Fail loud, not quiet. The email check is deliberate. auspex treats a malformed address as absent, so a device with a bad substitution would install, capture, and upload attributed to nobody — with nothing in status to say why. Failing the script surfaces it in the Rippling console instead. Confirm the resolved value on a pilot device before assigning to the fleet.

Step 3: Deploy the Package

In Rippling: Devices → Software → Add software, upload the .msi, and assign it to the same group as Step 2 as a required install.

Download the installer from:

https://auspex.span.app/releases/latest/windows/auspex_windows_amd64.msi
https://auspex.span.app/releases/latest/windows/auspex_windows_arm64.msi

The .msi is signed with a Windows code-signing certificate (Azure Trusted Signing), so policies requiring signed installers accept it.

On install it places the binary, writes the managed configuration marker, registers the machine-wide logon task, and converges the device to the managed tier.

Step 4: Smoke Test (before fleet rollout)

Assign Steps 2–3 to one or two pilot devices first. Confirm both report success in Rippling, then verify on-device from an elevated PowerShell:

& 'C:\Program Files\auspex\bin\auspex.exe' status
& 'C:\Program Files\auspex\bin\auspex.exe' auth show
schtasks /Query /TN "app.span.auspex"

Expect install mode: managed, daemon: ok, a token and work email both sourced from managed, and a registered logon task. Then have the pilot user sign in, use Claude Code or Cursor briefly, and confirm their traces reach the Span dashboard.

The engineer's own agent starts at sign-in. On a device where nobody has signed in since the install, status run as an admin will show the managed tier in place but no per-user daemon yet — that is expected.

Optional: Replace legacy Span coding-hooks in the same rollout

If your fleet still runs Span's earlier coding-hooks agent, retire it once auspex is confirmed healthy on each device — running both captures every event twice. See Retiring coding-hooks for a check-then-uninstall script that only acts on devices where auspex has genuinely taken over. Schedule it as a recurring Rippling script so it re-evaluates as the rollout lands.

Upgrading

Upload the new .msi to the existing software entry in Rippling. Assigned devices reinstall on their next check-in. The managed configuration and identity.json are preserved across the upgrade, and each engineer's captured data and hook wiring are left intact.

Uninstalling

Remove the software assignment in Rippling, or push msiexec /x with the auspex ProductCode as a script. The .msi deliberately leaves C:\ProgramData\auspex behind — the managed configuration and organization identity belong to you, not the installer, so a reinstall or version change never loses your fleet policy. Remove it explicitly when decommissioning:

Remove-Item -Recurse -Force 'C:\ProgramData\auspex'

Troubleshooting

  • install mode: user instead of managed — the managed configuration tree is missing. Confirm C:\ProgramData\auspex\managed.yaml exists; if the .msi installed but the marker is absent, the install did not complete.
  • token: not set after the identity script ran — check the file's encoding. A UTF-16 or BOM-prefixed identity.json is rejected; use the WriteAllText form in Step 2 exactly as given. auspex auth show names the problem when the file is present but unreadable.
  • work_email: (unset) with a token present — the address failed validation (it must look like name@domain.tld). A truncated or malformed value is dropped rather than sent, so check what Rippling's work-email variable actually resolved to on that device (the Step 2 script prints it on success).
  • No traces for a specific engineer — confirm they have signed in since the install (their agent starts at sign-in), then check auspex status in their session shows capture_wiring passing for all tools.
  • An Arm device shows the install as failed — you assigned the amd64 .msi. See Which architecture above.