-
Notifications
You must be signed in to change notification settings - Fork 1
Getting Started
This page walks one device through a complete first run: install the MSI, author a manifest with a single package, host it, run the CLI against it, and confirm the result from the log and the registry. Do it on a test machine you can wipe. It takes about fifteen minutes and does not require Autopilot, Intune or an MDM of any kind.
Download the MSI for your architecture from the repository's Releases page. The file is named
BootstrapMate-<arch>-<version>.msi, with <arch> being x64 or arm64. Releases built by
GitHub Actions are unsigned; sign them yourself, 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
The MSI does three things worth knowing about before you run it:
- It installs
managedbootstrapinstall.exeand the GUIBootstrapMate.exeintoC:\Program Files\BootstrapMate, and adds that directory to the systemPATH. - It registers a scheduled task named
BootstrapMate Self-Healthat runs daily at 03:00 asSYSTEM. -
It triggers that task immediately, at
InstallFinalize. The MSI also writes a defaultManifestUrlintoHKLM\SOFTWARE\BootstrapMate\Settings, so installing the MSI on a machine with network access starts a real run against that default manifest. On a test machine, set your ownManifestUrlfirst, or expect the first run in the log to be one you did not ask for.
Confirm the install:
managedbootstrapinstall.exe --version
--version (and its short form -V) is only honoured as the first argument. Anywhere else
it is silently treated as -v, meaning verbose.
A manifest has at most two root keys: setupassistant and userland. Each is an array of
items. Every item needs name, url, file and type. Nothing else is required.
Save this as bootstrapmate.json, replacing the URL with your own:
{
"setupassistant": [
{
"name": "Example Agent",
"url": "https://example.com/packages/ExampleAgent-1.0.0.msi",
"file": "ExampleAgent-1.0.0.msi",
"type": "msi"
}
],
"userland": []
}file is the name the download is written under inside
C:\ProgramData\ManagedBootstrap\cache. type may be msi, exe, ps1, nupkg or pkg.
YAML works too — the parser treats the manifest as YAML when the URL path ends .yaml or
.yml, or when the content does not begin with { or [.
MSI and EXE items are Authenticode-verified before they run, and verification is on by
default. If your test installer is unsigned, either sign it or add "allowUnsigned": true to
that item. A publisher mismatch is always refused regardless of allowUnsigned. See
Security and Package Verification.
Do not omit name on any item. The pre-run dialog listing reads name from every item in
both phases before the first install starts, so one missing name fails the whole run.
Put bootstrapmate.json and the installer it references behind HTTPS. Any static web host
works; no server-side logic is involved. If the manifest needs an Authorization header,
configure one — but note that BootstrapMate attaches it to package downloads only when the
package URL's host matches the manifest URL's host. For this first run, host both on the same
origin and skip authentication entirely. See
Serving Manifests and Packages.
From an elevated prompt:
managedbootstrapinstall.exe --url https://example.com/bootstrap/bootstrapmate.json --verbose
The CLI requires administrator rights. Unelevated and interactive, it offers to relaunch under
UAC; unelevated with --silent, it refuses and returns 1.
--verbose only affects the console — the log file always records everything, including
Debug. It is worth passing on a first run anyway, because some things are reported only at
Debug level: the absence of the optional progress dialog, and all output from sbin-installer.
Read the newest log. One file is written per run, named yyyy-MM-dd-HHmmss.log in local
time:
Get-ChildItem C:\ProgramData\ManagedBootstrap\logs -Filter *.log | Sort-Object LastWriteTime -Descending | Select-Object -First 1
A successful run contains === BootstrapMate Session Started ===, a
[SECTION] Processing Setup Assistant packages line, one [PROGRESS] Processing: <name> and
[SUCCESS] <name> installed successfully per item, and finally
[COMPLETION] BootstrapMate completed successfully! with a duration. Logs older than 30 days
are pruned automatically.
Read the registry status. Each phase writes its own key, in both the 64-bit and 32-bit views:
Get-ItemProperty 'HKLM:\SOFTWARE\Cimian\BootstrapMate\Status\SetupAssistant'
Get-ItemProperty 'HKLM:\SOFTWARE\Cimian\BootstrapMate\Status\Userland'
Stage should read Completed on a phase that ran and Skipped on a phase whose root key
was absent from the manifest. The key also carries StartTime, CompletionTime, ExitCode,
Architecture, BootstrapUrl, LastError and RunId.
A successful run additionally writes the build version it ran:
Get-ItemProperty 'HKLM:\SOFTWARE\Cimian\BootstrapMate' -Name LastRunVersion
Note the root: the values that describe a run live under HKLM\SOFTWARE\Cimian\BootstrapMate.
HKLM\SOFTWARE\BootstrapMate is written by the MSI and describes the install. Do not use
--status to check any of this — it reads the wrong root, and --clear-status clears nothing
real. See Troubleshooting and Gotchas.
Check the cache directory. On a successful install the downloaded file is deleted; on a failure it is kept on purpose, for inspection. So:
Get-ChildItem C:\ProgramData\ManagedBootstrap\cache
An empty directory is the healthy state. Any file in it is a failed install.
Do not treat exit code 0 as proof. Per-item failures are caught and the run continues, and a
run in which every item failed still exits 0 and still writes LastRunVersion. Count
Failed to install package lines in the log instead.
Once one item installs cleanly, add the real payload — normally the ongoing management agent — and decide how the manifest reaches devices. See Deployment for Intune and Autopilot delivery, Autopilot and the ESP for the device-phase timing, and Handoff to Cimian for what BootstrapMate should leave behind.