← Enterprise docs

Kandji deployment

A complete Kandji rollout requires:

  1. A Custom App with a pre-install script that writes /etc/preamp/bootstrap.env, then installs preamp-managed-<version>.pkg.
  2. A PPPC Library item granting Full Disk Access to the agent’s binary.

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

Prerequisites

  • Preamp admin console access (to generate an enrollment token).
  • Kandji tenant with permission to create Blueprints and Library items.
  • The signed preamp-managed-<version>.pkg. See Package downloads for the URL and SHA-256 verification steps.
  • 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 instead of attributing to a real person.

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. Create the Custom App in Kandji. Library → Add new → Custom App. Upload preamp-managed-<version>.pkg. Set Install Type to Audit and Enforce. In the Pre-install script field, paste:

    #!/bin/bash
set -euo pipefail

TOK="REPLACE_WITH_ORG_TOKEN"
EM="REPLACE_WITH_EMAIL_VARIABLE"   # Kandji's substitution token for the assigned user's email
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 REPLACE_WITH_ORG_TOKEN with the token from step 1. For the email variable, Kandji’s available substitution tokens depend on your blueprint configuration and ADE/Self Service integration; consult Kandji’s Custom Script variables documentation for the syntax in your tenant. The email must resolve to a verified-domain address for per-person attribution.

  3. Upload the PPPC profile. Use the PPPC template at installers/macos/pppc-template.xml in the agent repo. Fill in $TEAM_ID and $CODE_REQUIREMENT from the signed binary, then upload the resulting .mobileconfig via Library → Add new → Custom Profile. See the PPPC profile guide for the exact codesign invocations.

  4. Assign the Custom App and PPPC profile to the same Blueprint and scope it to the target devices.

  5. (Optional) Tune runtime settings via a Custom Profile. Create a Custom Profile with preference domain ai.preamp for schedule, allowUninstall, apiUrl, or other runtime knobs. See the managed preferences reference. Not required for enrollment.

Verification

On a target Mac after the Blueprint applies:

  • /etc/preamp/bootstrap.env is absent (the postinstall deletes it on successful enroll; presence means enroll failed, check the Kandji activity log).
  • The agent has Full Disk Access (grey toggle in System Settings → Privacy & Security).
  • The device shows up under the assigned user on app.preamp.ai/org/inventory/workforce. If it lands under Unattributed devices, 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.

Failure modes

  • Console user is root at install time. Postinstall logs no console user; deferring enroll until next policy run and leaves the bootstrap file in place. The next Blueprint run picks it up.
  • Bootstrap env file is malformed (typo, missing =). Agent’s parser rejects malformed lines and preamp enroll exits non-zero, visible in the Kandji activity log. Bootstrap file stays in place for diagnosis.
  • Email outside verified domains. Enroll succeeds, device lands in the unattributed bucket. Verify domains and re-run.

Uninstall

Create a second Custom App for preamp-uninstaller-<version>.pkg, set to Install once, and scope it to the devices that should be removed. If allowUninstall: true is set in a managed-prefs Custom Profile, the uninstaller also cleans up per-user data trees.

Trust note

The org token in the pre-install script is sensitive. It appears in Kandji’s script payload and activity logs. Treat it like any other secret in your MDM tenant. Rotate via app.preamp.ai → Settings → Enrollment tokens → Revoke if exposed.