Skip to content

Getting Started

Jump to bottom
Rod Christiansen edited this page Oct 8, 2026 · 3 revisions

Getting Started

This page walks one device through a first run: install the MSI, write a one-package manifest, host it, run the CLI against it, and confirm the result. Do it on a test machine you can wipe. It takes about fifteen minutes and needs no Autopilot, Intune or MDM.

1. Install the MSI

Download the MSI for your architecture from the repository's Releases page: BootstrapMate-<arch>-<version>.msi, where <arch> is x64 or arm64. Release builds are unsigned; sign them, or build locally, before shipping to a fleet. See Building and Signing.

Install it from an elevated prompt:

msiexec /i BootstrapMate-x64-<version>.msi /qn

Three things to know before you do:

  • It installs managedbootstrapinstall.exe and the Managed Bootstrap Install app into C:\Program Files\BootstrapMate, and adds that directory to the system PATH.
  • It registers a scheduled task, BootstrapMate Self-Heal, that runs daily at 03:00 as SYSTEM.
  • It starts that task straight away. The MSI also writes a default ManifestUrl into HKLM\SOFTWARE\BootstrapMate\Settings, so installing it on a machine with network access starts a real run against that default manifest. On a test machine, set your own ManifestUrl in policy first, or expect a first run in the log that you did not ask for.

Confirm the install:

managedbootstrapinstall.exe --version

2. Write a minimal manifest

A manifest has up to three root keys: preflight, setupassistant and userland. Each is an array of items, and every item needs name, url, file and type. Save this as bootstrapmate.json, with your own URL:

{
  "setupassistant": [
    {
      "name": "Example Agent",
      "url": "https://example.com/bootstrap/packages/ExampleAgent-1.0.0.msi",
      "file": "ExampleAgent-1.0.0.msi",
      "type": "msi"
    }
  ],
  "userland": []
}

file is the name the download is written under in C:\ProgramData\ManagedBootstrap\cache. type is msi, exe, ps1, nupkg or pkg. YAML works too; see Manifests.

To pin the download, add the file's SHA-256 as "hash":

(Get-FileHash .\ExampleAgent-1.0.0.msi -Algorithm SHA256).Hash.ToLower()

MSI and EXE items are Authenticode-verified before they run, which is on by default. If your test installer is unsigned, sign it or add "allowUnsigned": true to the item. A publisher mismatch is refused regardless. See Security and Package Verification.

3. Host it

Put bootstrapmate.json and the installer behind HTTPS. Any static web host works. If the manifest needs an Authorization header, note that BootstrapMate sends it to package downloads only when the package's host matches the manifest's host. For a first run, host both on the same origin and skip authentication. See Serving Manifests and Packages.

4. Run it

From an elevated prompt:

managedbootstrapinstall.exe --url https://example.com/bootstrap/bootstrapmate.json --verbose

Unelevated, the CLI offers a UAC relaunch on an interactive console and otherwise exits 3. --verbose affects only the console; the log always records everything. Some things are reported only at Debug level, such as a missing progress dialog and sbin-installer's output.

The exit code tells you the outcome: 0 clean, 2 at least one package failed, 1 the manifest could not be fetched or parsed, 3 not elevated.

5. Confirm the result

Read the last-run summary.

managedbootstrapinstall.exe --last-run

A clean run reads provisioning completed with failed=0. The full record is C:\ProgramData\ManagedBootstrap\last-run.json, with one entry per item.

Read the log. Each run has its own directory, C:\ProgramData\ManagedBootstrap\logs\yyyy-MM-dd\HHmmss\, holding bootstrap.log, events.jsonl and session.json:

Get-ChildItem C:\ProgramData\ManagedBootstrap\logs -Filter *.log -Recurse | Sort-Object LastWriteTime -Descending | Select-Object -First 1

A successful run contains === BootstrapMate Session Started ===, [SECTION] Processing Setup Assistant packages, a [PROGRESS] Processing: <name> and [SUCCESS] <name> installed successfully per item, [COMPLETION] BootstrapMate completed successfully! and === BootstrapMate Session Ended ===. A run with failures ends [COMPLETION] BootstrapMate completed with N failed package(s).

Read the registry status.

managedbootstrapinstall.exe --status

SetupAssistant should read Completed; Userland reads Completed for an empty array and Skipped for a missing one; Preflight reads Skipped because this manifest has none. The values live under HKLM\SOFTWARE\BootstrapMate\Status\.

Check the cache. A downloaded file is deleted after a successful install and kept after a failed one, so an empty directory is healthy:

Get-ChildItem C:\ProgramData\ManagedBootstrap\cache

Next

Once one item installs cleanly, add the real payload, normally the ongoing management agent, and decide how the manifest reaches devices. Add a preflight script when the same manifest should also keep provisioned machines current through the daily task. See Deployment, Preflight and Baseline, Autopilot and the ESP and Handoff to Cimian.

See also

Introduction

The Manifest

Configuration

Operations

More

Clone this wiki locally