Lifecycle Hooks and Windows SYSTEM Account
This information applies to Windows only.
Architect Agent runs as a Windows service. All lifecycle hook scripts placed in the `lifecycle_hooks` directory are executed under the `NT AUTHORITY\SYSTEM` account, not your user account.
Scripts that work when double-clicked or run from your command prompt may silently fail or produce errors when executed by the Agent.
Why scripts fail under SYSTEM
Programs installed with the "Install for current user only" option (e.g. Git, Python) are added to your user's PATH variable. The SYSTEM account has a separate PATH and does not inherit your user's entries.
When a lifecycle hook calls `git` or `python` by name, SYSTEM cannot locate the executable.
The SYSTEM account additionally differs from your user account in the following ways:
| Difference | SYSTEM | Your user |
|---|---|---|
| Home directory | `C:\Windows\system32\config\systemprofile` | `C:\Users\YourName` |
| PATH variable | System-wide entries only | System-wide + user entries |
| Environment variables | `%USERPROFILE%`, `%APPDATA%` point to SYSTEM profile | Point to your profile |
| Network drives | Not available | Available |
Writing SYSTEM-safe scripts
Use absolute paths to all executables. Do not rely on PATH or user-specific environment variables.
Example `lifecycle.pre-start.bat` that will not work under SYSTEM:
@echo off
git pull origin main
Corrected version using absolute paths:
@echo off
"C:\Users\YourName\AppData\Local\Programs\Git\cmd\git.exe" pull origin main
Git installed per-user is located at `C:\Users\{username}\AppData\Local\Programs\Git\cmd\git.exe`. To find the absolute path of any program, open a command prompt and run:
where git
Rules
| Rule | Details |
|---|---|
| Use absolute paths | `"C:\Users\YourName\AppData\Local\Programs\Git\cmd\git.exe"` instead of `git` |
| Quote paths with spaces | `"C:\Program Files\7-Zip\7z.exe"` |
| Avoid user environment variables | `%USERPROFILE%` and `%APPDATA%` resolve to the SYSTEM profile |
| Avoid mapped network drives | Use UNC paths instead (`\\server\share\folder`) |
Testing
To simulate the SYSTEM context, run your script with `psexec -s cmd` from an elevated command prompt. This will open a shell running as SYSTEM, allowing you to verify that all paths resolve correctly before deploying the script as a lifecycle hook.