auspex: IT Admin User Guide for Hexnode UEM (Windows)

Last updated: September 29, 2026

This guide covers deploying the Span agent (auspex) to Windows devices with Hexnode UEM. 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.
  • A Hexnode UEM portal with target Windows devices enrolled through the Hexnode Installer, so the Hexnode agent is present — Hexnode needs it for MSI installs (except on Windows 11) and for custom scripts.
  • Windows 10 (build 1809+) or Windows 11, Pro, Enterprise or Education edition. Hexnode does not support app deployment or custom scripts on Windows Home.
  • Each device assigned to a Hexnode user whose email is the engineer's work email (a local Hexnode user, or one synced from Entra ID, Google Workspace, Okta or Active Directory) — it identifies the individual on their device. Hexnode's %email% wildcard resolves from that user.
  • The Windows packages (download the build matching your devices' architecture, then upload it):
    • amd64 — Intel/AMD, almost every PC: https://auspex.span.app/releases/latest/windows/auspex_windows_amd64.msi — click here to download
    • arm64 — Windows on Arm devices only: https://auspex.span.app/releases/latest/windows/auspex_windows_arm64.msi — click here to download

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

Run this one-liner against your Windows devices with Manage → Devices → Actions → Others → Execute Custom Script (save it as a .ps1 first), then read each device's result in Action History → Show Output — or tick Store output in custom attribute to see it as a column in the device list:

"$env:COMPUTERNAME,$env:PROCESSOR_ARCHITECTURE"

AMD64 → the amd64 build. ARM64 → the arm64 build. If any Arm devices appear, add the arm64 .msi as a second Enterprise App and target it at a device group containing just those devices.

Deployment order (important)

  1. Identity script that writes identity.json — before or with the package.
  2. The package (Enterprise App, pushed with a Required Apps policy).

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.

The token itself is on the Traces settings page: open the Trace collection card and click View token. It's shown there regardless of which tools are toggled on above, and it's the same span_… org-wide value every device uses. That page is limited to Span admins and users whose permission group can manage integrations — if it doesn't load for you, ask one of them to fetch the token.

Step 2: Deliver the Identity File

The token is org-wide; the work email is per-device. Hexnode passes the device user's email into the script as an argument via its %email% wildcard, so one script serves the whole fleet. Hexnode runs custom scripts in the background with system privileges.

Save this as auspex-identity.ps1, replacing <YOUR_TOKEN> with the token from Step 1:

$ErrorActionPreference = 'Stop'

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

# Passed by Hexnode: set the script's Arguments field to %email%
$Email = [string]$args[0]

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"

To deploy:

  1. Upload the script to Content → My Files (so you can reuse it from actions, policies and automations).
  2. Manage → Devices, select the target devices, then Actions → Others → Execute Custom Script.
  3. Choose the script from the Hexnode repository and enter %email% in Arguments. Keep the default timeout (15 minutes or more).
  4. Run it, then check each device's Action History → Show Output for Success: identity.json written for ….

For devices that enroll later, add the same script to an automation: Automate → New Automation → Windows → Execute Custom Scripts, trigger On Device Enrollment, with the same %email% argument.

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 an unresolved wildcard would install, capture, and upload attributed to nobody — with nothing in status to say why. Failing the script surfaces it in Hexnode's Action History instead. Confirm the resolved value on a pilot device before assigning to the fleet.

Step 3: Deploy the Package

  1. Apps → + Add Apps → Enterprise App, platform Windows, and upload the .msi. Hexnode reads the app version and installer identifier from the package itself.
  2. Under Success Criteria, choose Install Path and enter C:\Program Files\auspex\bin\auspex.exe.
  3. Policies → New Policy → New Blank Policy, then Windows → App Management → Required Apps → Configure, and add the auspex app.
  4. Policy Targets: the same devices/groups as Step 2, then Save.

Hexnode always installs MSIs with /i … /quiet, so the install is silent, and Required Apps periodically checks the device and reinstalls auspex if it goes missing. No extra command-line arguments are needed.

Download the installer — pick the build matching the target devices' architecture (see Which architecture above):

  • amd64 — Intel/AMD, almost every PC: https://auspex.span.app/releases/latest/windows/auspex_windows_amd64.msi — click here to download
  • arm64 — Windows on Arm devices only: https://auspex.span.app/releases/latest/windows/auspex_windows_arm64.msi — click here to download

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 each device's Action History, 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. Add it as a Hexnode Scripts policy (Policies → New Policy → Windows → Configurations → Scripts) that repeats on User logon or Device startup, so it re-evaluates as the rollout lands.

Upgrading

Upload the new .msi to Hexnode (Apps → + Add Apps → Enterprise App; Hexnode keeps multiple versions of an MSI app), then select the new version in the Required Apps policy. Targeted devices install it 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 auspex app from the Required Apps policy first (otherwise Hexnode reinstalls it), then use Actions → Applications → Uninstall Application, or push msiexec /x with the auspex ProductCode through Execute Custom 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 Hexnode's %email% wildcard actually resolved to on that device (the Step 2 script prints it on success, in Action History → Show Output).
  • 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.
  • The identity script fails with Could not resolve a valid work email (got '') — the device isn't assigned to a Hexnode user with an email, or the Arguments field isn't exactly %email%.
  • The app or script never runs on a device — confirm it was enrolled through the Hexnode Installer (the Hexnode agent is required for MSI installs and custom scripts) and isn't running Windows Home.
  • MSI error 1618 — another installation was in progress; Required Apps retries on its next check. 1603 usually means a conflicting existing install — check auspex status and the device's Applications list.