FAQ

FAQ

Is this actually outset, or just inspired by it?

It is a port: the same directory names, the same once/every split, the same ignored-users, overrides and checksum concepts, the same trigger-file pattern. The execution model underneath is entirely Windows — one LocalSystem service instead of a LaunchDaemon plus a LaunchAgent — and that difference is where the behavioural divergences come from. See Coming From Outset.

Why is the CLI called managedstatekeeper.exe and the data directory ManagedState?

The project is StartSet; the shipped CLI binary is renamed to managedstatekeeper.exe at publish time and the payload tree lives at C:\ProgramData\ManagedState. Only the binaries live under C:\Program Files\StartSet. Anything that invokes the CLI by path must use managedstatekeeper.exe.

Can I write payloads in Python, VBScript or as .reg files?

Not directly. There is no shebang mechanism and the extension chooses the processor. Supported extensions are .ps1, .cmd, .bat, .exe, .msi and .msix. Adding an extension to allowed_extensions makes it discoverable but there is no processor for it, so it fails with UnsupportedType. Wrap the thing you want to run in a .ps1 or .cmd.

Why did my script in login-every\MyApp\Setup.ps1 never run?

Discovery is top level only — subdirectories are never walked, and nothing reports the file as missing. Put payloads flat in the directory.

Do login payloads run when a user unlocks the screen?

No. StartSet watches logon events (Security 4624, types 2, 10 and 11). Unlock is type 7 and is not watched.

Will payloads run over RDP?

Yes — logon type 10 is watched. But user-context payloads are launched into the active console session, so on a machine with several sessions the payload goes to the console one. If nobody is at the console, a user-context payload is deferred rather than run in the wrong place.

My login script writes to HKCU and nothing happens. Why?

Either it is in a privileged directory, or it is a package. login-privileged-*, boot-* and on-demand-privileged payloads run as LocalSystem in session 0, where HKCU is SYSTEM's hive and desktop APIs do nothing. .msi and .msix payloads are never routed into the user's session either. Per-user work belongs in login-once, login-every or on-demand, as a script. See Windows Session Model.

How do I get elevation and the user's hive in one payload?

You cannot, and no configuration changes that. Split the work: a privileged payload computes and stages what it needs into a readable location such as C:\ProgramData\ManagedState\share, and a login-every payload consumes it as the user.

What does Deferred mean, and should I alert on it?

It means the payload did not run because the console user's session could not be reached — not that it failed. In reports\items.json it appears as Pending. Treat it as a state to watch rather than an incident: the next sign-in retries. Alert on a payload that stays Pending across many sessions and many machines, not on a single occurrence.

Why did my login-privileged-once payload only run for the first user on the machine?

Because it is tracked in runonce-system.json, not per user. StartSet uses a per-user ledger only for login-once, login-every and on-demand. If you need per-user semantics, use login-once. This is a real divergence from outset.

How do I make a *-once payload run again?

Edit it. The ledger stores the payload's SHA256 and a content change re-arms it. Failing that, add it to overrides (runs every time, ledger untouched) or clear the ledger entry:

managedstatekeeper remove-override MyPayload.ps1 --clear-runonce --user jsmith

What happens if a *-once payload fails?

Only a successful run is recorded, so it will be retried at the next matching trigger. A boot-once payload is deleted from disk only after success.

Which PowerShell runs my scripts?

PowerShell 7 (pwsh.exe) if it is installed, otherwise Windows PowerShell 5.1. Arguments are -NoProfile -NonInteractive -ExecutionPolicy Bypass -File, and the working directory is the payload directory. Test your payload the same way or you will hit differences you did not expect.

Do I need to relax the PowerShell execution policy?

No. Payloads are invoked with -ExecutionPolicy Bypass.

Can a standard user drop a script into boot-every and get SYSTEM execution?

No. Payloads in elevated directories must be owned by SYSTEM, the built-in Administrator, Administrators, or a service SID; anything else is skipped with Permission validation failed. That said, the check is on ownership rather than ACLs, so the ACLs on C:\ProgramData\ManagedState are still worth reviewing in a hostile environment.

Does StartSet download anything?

No. It has no repository, no update mechanism and no network client beyond a connectivity check (interface state, IPv4 default gateway, and a WMI fallback). It executes what is already on disk.

How do I run something right now, without a reboot or a sign-out?

For a specific payload type, from an elevated shell:

managedstatekeeper process boot-every

To go through the service — which is what you want for user-context payloads:

New-Item -ItemType File 'C:\ProgramData\ManagedState\.startset.ondemand' -Force

To re-run boot payloads the way the service does:

Restart-Service StartSet

Does restarting the service re-run boot-every?

Yes. BootWorker runs at service start, not at OS boot specifically. That is the supported way to test boot payloads — and something to remember before restarting the service on a live machine.

Can payloads run in parallel?

No. parallel_execution exists in the config schema but is not implemented; setting it logs a warning and execution stays sequential in case-insensitive alphabetical order.

How do I control ordering?

Prefix filenames. 10-, 20-, 90- is the usual convention.

Where are the logs, and how long are they kept?

Per-run directories under C:\ProgramData\ManagedState\logs\YYYY-MM-DD\HHMM\, plus aggregated reports\, plus Warning-and-above in the Windows Application event log under source StartSet. Retention is 30 days. Anything a payload writes loose into the logs directory is also aged out at 30 days, so put payload output elsewhere. See Logging and Reporting.

Why does --verbose not make anything more verbose?

It is registered as a global option but no handler reads it — the log level comes from Config.yaml. Set log_level: debug and restart the service.

Why did my Config.yaml change do nothing?

Either the service was not restarted (preferences load once at start-up) or the key is misspelled (unknown keys are ignored silently). Watch for ignored_network_failure, which has the -ed.

Can I trust the exit code?

Only partly. A non-zero exit means a payload ran and returned non-zero. Timeouts, deferrals, skipped permission and checksum checks, and unsupported extensions all leave the exit code at 0. Read reports\items.json for the real picture.

Are the GitHub releases signed?

No. The release workflow builds unsigned binaries and publishes startset-x64.zip and startset-arm64.zip only. Sign them with your own certificate before fleet deployment — the release notes include the signtool commands, and so does Installation.

Does uninstalling remove my payloads and run-once state?

No. C:\ProgramData\ManagedState survives both the MSI uninstall and a manual removal, so a reinstall does not re-run every once payload. Delete it explicitly for a clean slate.

Does StartSet work on Windows Server or in a container?

Nothing prevents it — the manifests declare Windows 10/11 compatibility and the code uses no client-only APIs — but Server is not exercised by the repository's CI or tests. Session 0 constraints are, if anything, more pronounced in a server or container context, and user-context payloads need a console session that may never exist there.