claudetools/.claude/memory/reference_gururmm_user_session_context.md

name, description, metadata

name	description	metadata
gururmm-user-session-context	GuruRMM commands accept context=user_session (migration 041) to run as the active logged-on user via WTS impersonation — executes previously-interactive-only commands that fail as SYSTEM with "NonInteractive mode"	type reference

GuruRMM's command API (POST /api/agents/:id/command, see reference_gururmm_api) accepts an optional context field:

• "system" (default) — Session 0 / SYSTEM, the original behavior of every existing command.
• "user_session" — runs in the active logged-on user's desktop session via WTS token impersonation (WTSQueryUserToken + DuplicateTokenEx + CreateProcessAsUserW, in agent/src/watchdog/wts.rs). Requires an active logged-on user on the endpoint — no user logged in = no session to run in.

Added by migration 041_add_command_context.sql; server enum CommandContext serializes snake_case.

Why it matters: some Windows cmdlets fail as SYSTEM with a "NonInteractive mode" / interactive-session error and historically had to be done by hand on-site. user_session runs them remotely instead. Verified 2026-05-27 on the Peaceful Spirit BridgetteHome L2TP VPN deploy: Set-VpnConnection -L2tpPsk -AllUserConnection — previously documented as "cannot be done remotely" — was set successfully via user_session, completing a VPN rollout entirely through RMM with no on-site visit.

Elevation: the WTS-impersonated token of a logged-on admin user comes back effectively elevated (WindowsPrincipal.IsInRole(Administrator)=True) — enough to write the all-user phonebook / HKLM. A standard logged-on user would NOT be elevated, so admin-requiring commands would still fail. The agent still launches powershell.exe -NonInteractive, so don't rely on real interactive prompts.

Invoke: body {"command_type":"powershell","command":"...","context":"user_session"}. To dodge shell-quoting on multi-line scripts, base64-encode the script as UTF-16LE and send powershell -NoProfile -NonInteractive -EncodedCommand <b64> (iconv is absent in this Git Bash — encode with py).