Managed preferences reference

Deploy a macOS configuration profile with preference domain ai.preamp to configure the Preamp agent on managed Macs. The keys below describe everything the agent and its installer scripts read from that profile.

The managed-prefs profile is for runtime tuning only (schedule, full-backup interval, allow-uninstall, custom apiUrl). Enrollment is a separate mechanism, documented in the next section.

Per-human attribution (bootstrap.env)

The recommended way to enroll a managed device is to drop a file at /etc/preamp/bootstrap.env (macOS, Linux) or pass MSI properties (Windows) before the agent’s first run. The agent reads three values:

Variable	Required	Purpose
`PREAMP_ORG_TOKEN`	yes	One-time org enrollment token from `app.preamp.ai → Settings → Enrollment tokens`.
`PREAMP_USER_EMAIL`	recommended	When the email’s domain is verified for the org under `app.preamp.ai → Settings → Domains`, the server creates or reuses a per-person member for this user. Without it, the device lands in the per-org unattributed bucket on the Workforce tab.
`PREAMP_USER_NAME`	optional	Display name shown on the Workforce tab.

Format of /etc/preamp/bootstrap.env:

PREAMP_ORG_TOKEN=eyJ...
PREAMP_USER_EMAIL=alice@acme.com
PREAMP_USER_NAME=Alice Smith

File must be mode 0600, owned by root. The .pkg postinstall runs as root: it copies the file to a per-install temp under /var/tmp owned by the console user (mode 0600, removed on exit regardless of outcome), then runs preamp enroll --env-file=<temp> as the console user via sudo -H -u. The original at /etc/preamp/bootstrap.env stays root-owned and is deleted on successful enroll. The console user never reads the original file.

Platform-specific deployment guides:

Re-running an MDM policy on an already-enrolled device is safe; preamp enroll is idempotent.

macOS managed package preinstall requirement (enrollmentToken)

The shipping preamp-managed-<version>.pkg (as of v1.0.3) has a preinstall gate: its preinstall script aborts the entire install unless /Library/Managed Preferences/ai.preamp.plist exists and contains an enrollmentToken key. If the profile is missing, the install fails with a generic “contact the software manufacturer” error and no useful diagnostic in the MDM policy log.

To satisfy the gate, deploy an ai.preamp Configuration Profile carrying an enrollmentToken key (value: your org enrollment token) and confirm it has installed on the device before the deployment policy runs.

Key	Type	Required	Consumed by	Notes
`enrollmentToken`	string	yes (macOS pkg)	pkg preinstall gate	Presence is checked by the preinstall script. Set the value to your org enrollment token. The actual token used for enrollment still comes from `PREAMP_ORG_TOKEN` in `bootstrap.env`; if you point the bootstrap script at this key (via `defaults read`), the two are the same token.

This gate is independent of the bootstrap.env enrollment flow above: bootstrap.env supplies the token that preamp enroll actually uses, while enrollmentToken in managed prefs is only a presence check performed before the package is allowed to install. Both must be satisfied on the shipping macOS package.

Identity Configuration Profile (ai.preamp.identity)

JAMF (and other MDMs) substitute inventory variables like $EMAIL / $REALNAME only inside Configuration Profile payloads, never inside policy script parameters. The macOS deployment guides therefore carry the assigned user’s identity in a separate ai.preamp.identity Configuration Profile, which the bootstrap script reads via defaults read and writes into bootstrap.env.

Key	Type	Required	Read by	Notes
`email`	string	recommended	MDM bootstrap script	Populated via the MDM’s email substitution variable (JAMF `$EMAIL`). Becomes `PREAMP_USER_EMAIL`. Must be a verified-domain address for per-person attribution.
`fullname`	string	optional	MDM bootstrap script	Populated via the MDM’s real-name substitution variable (JAMF `$REALNAME`). Becomes `PREAMP_USER_NAME`.

These keys are read by the deployment-side bootstrap script, not by the agent runtime. See the JAMF deployment guide for the exact script.

Keys

Key	Type	Required	Default	Consumed by	Notes
`apiUrl`	string	no	`https://api.preamp.ai`	agent runtime	Regional or air-gapped endpoint. Override only if you’ve been issued a non-default URL.
`managed`	bool	yes	n/a	agent runtime	Set to `true`. Disables the agent’s self-update behavior so that all upgrades flow through your MDM.
`schedule`	string	no	(server default)	agent runtime	One of `15min`, `30min`, `hourly`, `daily`. Overrides the server-side device config value.
`allowUninstall`	bool	no	`false`	uninstaller postinstall script	When `true`, the uninstaller `.pkg` removes per-user `~/.preamp` and `~/.local/share/preamp` trees in addition to the system install.
`minFreeDiskSpaceGB`	int	no	`1`	agent runtime	Skip a sync if less than this much disk space is free.
`autoApprovePaths`	bool	no	`false`	agent runtime	Set to `true` to skip the candidate review step before adding new backup paths.

Precedence

For settings managed by this profile, the runtime precedence is two-tier:

Managed prefs (this profile). Overrides server-side device config when both specify the same key.
Server-side device config. Applies when the key is absent from managed prefs.

CLI flags (e.g. preamp paths add --provider, preamp schedule <interval>) affect per-invocation command behavior only. They do not change the merged effective config that the agent reads on its scheduled runs. There is no third precedence tier for CLI flags vs. managed/server config.

File path

/Library/Managed Preferences/ai.preamp.plist. Read-only for the agent; written by macOS MDM.

Example profile snippet

<dict>
  <key>managed</key><true/>
  <key>schedule</key><string>hourly</string>
  <key>allowUninstall</key><false/>
</dict>

JAMF deployment
Kandji deployment
Intune / Mosyle deployment
PPPC profile guide (required for Full Disk Access)