Bootstrap Token Deployment

Bootstrapping lets you link a Pult Agent installation to a user account without requiring the employee to sign in manually. A bootstrap token -- created in the Pult Dashboard -- is deployed to the device so the agent can automatically initiate enrollment. This page covers how to deploy the bootstrap token via command-line flags, MSI installer properties, or file-based deployment.

How It Works

1. An admin creates a bootstrap token in the Pult Dashboard.
2. The token is deployed to the device via one of the supported methods (CLI, MSI property, or file).
3. The agent reads the token and initiates a Device Auth Request, sending basic device information (device name, OS, serial number).
4. The request appears under Settings → Presence → Device Authentication → Pending Requests.
5. An admin reviews and approves the request, matching it to a Pult user.
6. The agent receives an access token and the device is fully enrolled.

Creating a Bootstrap Token

1. In the Pult Dashboard, go to Settings → Presence → Device Authentication.
2. In the Bootstrap Tokens section, click Create Token.
3. Enter a name (e.g., "Q1 2026 Rollout") and set an expiration date.
4. Click Create. The token is displayed once -- copy it immediately and store it securely.

Token Lifecycle

• Active -- The token is valid and can be used for new enrollments.
• Expired -- The token has passed its expiration date and can no longer be used.
• Revoked -- The token was manually revoked by an admin.

You can view and manage all tokens in the Bootstrap Tokens table on the Device Authentication page.

Token Format

Bootstrap tokens must be:

• 1-128 characters long
• Alphanumeric characters, hyphens (-), and underscores (_) only

Invalid or expired tokens are rejected server-side (see agent logs for detail).

Deploying the Token

Three deployment methods are available. Pick one that fits how your MDM or tooling runs installers (user vs SYSTEM context matters on Windows).

Method 1: Command-Line Flag

Run the agent binary with the --bootstrap-token flag. The command writes the token to secure storage and exits immediately -- it does not start the agent. See the CLI reference for full flag semantics.

macOS:

"/Applications/Pult Agent.app/Contents/MacOS/pult-agent" --bootstrap-token "your-token-here"

Windows:

"C:\Program Files\Pult Agent\pult-agent.exe" --bootstrap-token "your-token-here"

If your MDM can run a script after installing the canonical Pult Agent.pkg (e.g. Kandji), see macOS Deployment via Post-install Script. For most macOS rollouts, the wrapper .pkg approach (token file embedded in a postinstall script) is simpler -- see Build the macOS MDM Package.

Updating a deployed token via CLI

To rotate the token on an already-running agent, set the new value with --bootstrap-token, then signal a reload with --reload-bootstrap-token. See the CLI reference -- Common compositions for the exact two-line recipe. If the agent is not running, the new token takes effect at next launch -- no reload needed.

Method 2: MSI Properties (Windows Only)

During install or upgrade:

msiexec /i pult-agent.msi BOOTSTRAP_TOKEN="your-token-here" AUTOLAUNCHAPP=1

The installer runs pult-agent.exe --bootstrap-token in user context after setup. Behavior:

• Fresh install: the agent starts automatically when AUTOLAUNCHAPP=1 is set.
• Upgrade or reinstall: the agent is closed, reinstalled, the token is set, and the agent restarts automatically.
• Token timing: the token is written to secure storage before the agent starts, so it is available on first run.

Use AUTOSTART_ALLUSERS=0 only when you intentionally disable that registry-based auto-start (default is 1, so you normally omit the property).

Method 3: File-Based Deployment

Place a plain-text file containing the token in a watched directory. The agent imports it into secure storage, then deletes the file. This is an alternative deployment method for MDMs where passing command-line arguments or MSI properties is difficult or unreliable.

Valid file names (case-insensitive): BOOTSTRAP_TOKEN, BOOTSTRAP-TOKEN, BOOTSTRAP-TOKEN.txt

File locations (first valid file found is used):

The file must contain only the token text (no formatting, no newlines). After the agent reads the token:

1. The token is transferred to secure storage (Keychain / Credential Manager).
2. The token file is automatically deleted.

This method works well when:

• Your MDM runs installers in SYSTEM context (where MSI properties don't work).
• You need to separate app installation from token provisioning.
• You want a cross-platform approach that works identically on Windows and macOS.
• Post-install scripts cannot easily execute the agent binary with arguments.

Updating a deployed token: drop a fresh token file at the same watched path. A running agent picks it up automatically and replaces the stored token; no restart required.

Manual Deployment Walkthrough

For documentation purposes, this section walks through the simplest possible deployment of the Pult Agent as two independent steps:

1. Install the agent -- using the provided installer (.msi, .pkg, .dmg, or .deb).
2. Drop the bootstrap token -- writing a token file to the watched location.

The two steps can run in either order. The agent picks up the token the next time it starts (or immediately, if it is already running). Either step can be performed manually, by an MDM, or by any custom tooling.

Step 1: Install the agent

Use the provided installer. The exact command does not matter; pick whatever your tooling supports. See Installation for details and download links.

On Windows, the MSI registers login auto-start by default (AUTOSTART_ALLUSERS=1) -- the agent starts at next login if not launched explicitly. On macOS, configure managed login items so the agent auto-starts under MDM management.

Step 2: Drop the bootstrap token

Write a file containing the token to one of the watched paths from Method 3. The agent will consume it on next launch (or immediately, if already running).

Windows (PowerShell, user context)

$BootstrapToken = "your-bootstrap-token-here"
$TokenDir = "$env:APPDATA\com.pult.agent"
$TokenFile = Join-Path $TokenDir "BOOTSTRAP_TOKEN"

if (-not (Test-Path $TokenDir)) {
    New-Item -ItemType Directory -Path $TokenDir -Force | Out-Null
}

Set-Content -Path $TokenFile -Value $BootstrapToken -NoNewline

Write-Host "Bootstrap token written to $TokenFile"

$AgentPath = "C:\Program Files\Pult Agent\pult-agent.exe"
if (Test-Path $AgentPath) {
    Start-Process -FilePath $AgentPath
    Write-Host "Pult Agent launched"
}

macOS (bash, runs as the logged-in user)

#!/bin/bash
set -euo pipefail

BOOTSTRAP_TOKEN="your-bootstrap-token-here"
TOKEN_DIR="${HOME}/Library/Application Support/com.pult.agent"
TOKEN_FILE="${TOKEN_DIR}/BOOTSTRAP_TOKEN"

/bin/mkdir -p "${TOKEN_DIR}"
echo -n "${BOOTSTRAP_TOKEN}" > "${TOKEN_FILE}"

echo "Bootstrap token written to ${TOKEN_FILE}"
exit 0

macOS (bash, runs as root, writes as console user)

#!/bin/bash
set -euo pipefail

BOOTSTRAP_TOKEN="your-bootstrap-token-here"

CONSOLE_USER="$(/usr/bin/stat -f%Su /dev/console)"
if [[ -z "${CONSOLE_USER}" || "${CONSOLE_USER}" == "root" ]]; then
  echo "No interactive console user detected. Exiting (nothing to do)."
  exit 1
fi

USER_HOME=$(/usr/bin/dscl . -read /Users/"${CONSOLE_USER}" NFSHomeDirectory | awk '{print $2}')
TOKEN_DIR="${USER_HOME}/Library/Application Support/com.pult.agent"
TOKEN_FILE="${TOKEN_DIR}/BOOTSTRAP_TOKEN"

/usr/bin/sudo -u "${CONSOLE_USER}" /bin/mkdir -p "${TOKEN_DIR}"
/usr/bin/sudo -u "${CONSOLE_USER}" /bin/bash -c "echo -n '${BOOTSTRAP_TOKEN}' > '${TOKEN_FILE}'"

echo "Bootstrap token written to ${TOKEN_FILE}"
exit 0

A useful property of the file-based approach: writing the token does not require an active user session. As long as the user's home directory exists, the script can run before the user logs in for the first time -- the agent will consume the file when it eventually starts.

Security Considerations

• Tokens are stored in OS secure storage (macOS Keychain / Windows Credential Manager) after consumption. Tokens passed via MSI properties are handled securely by Windows Installer.
• File-based tokens are stored in plain text temporarily on disk. The agent deletes the file after reading. Use short-lived bootstrap tokens when practical.
• Directory permissions: on Windows, prefer %APPDATA%\com.pult.agent\. If you must use %PROGRAMDATA%, ensure appropriate ACLs are set so the user-context agent can delete the consumed token. On macOS, the token lives in the user's home directory with standard user permissions.
• Avoid logging tokens. Prefer MDM secret variables or parameters rather than hard-coding in shared scripts.
• Token validity is enforced server-side -- expired or revoked tokens are rejected.
• Always corroborate time, network, and IP when approving device authentication -- device fields such as OS, username, serial number, or device name can be misrepresented. See Device Authentication.

Troubleshooting

Agent ignores --bootstrap-token while running

Symptom: Tray app stayed up; new token not used.

Fix: Run --reload-bootstrap-token after --bootstrap-token, or restart the agent. See the CLI reference -- Common compositions for the exact two-line invocation.

"Invalid bootstrap token provided"

Confirm length and character rules under Token Format.

macOS: Token set but app never appears

Confirm /Applications/Pult Agent.app exists and launch manually:

open -a "Pult Agent"

Token file never disappears

Check folder permissions, MDM execution context (SYSTEM vs user), and agent logs under Troubleshooting.

Next Steps

• Microsoft Intune (Windows)
• Build the macOS MDM Package
• Device Authentication