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.

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>