#8 [Architecture] Local\\ vs Global\\ Mutex namespace for single-instance

[Anonymous]

Originally created by: phantasmat2018

Status: Architecture decision, archived for reference.

CapyBro uses a Local\CapyBroV2 named mutex for single-instance enforcement (each Windows session gets its own slot, so two users on the same machine can both run CapyBro independently).

This was a deliberate change from the Global\ namespace, which:

• Required SeCreateGlobalPrivilege (held only by Administrators + INTERACTIVE)
• Broke silently on kiosk machines / Group Policy lockdowns / non-admin desktops
• Prevented two RDP sessions from running CapyBro simultaneously

Trade-off

Local\ namespace means:

• • Works without admin rights, on any kiosk / RDP / locked-down corporate machine
• • Each Windows session has its own instance
• • Can't enforce "one instance across the whole machine" if you really want that
• • The activation EventWaitHandle is also session-scoped (can't activate across sessions)

Why this is documented as an issue

If anyone ever proposes "let's switch back to Global\" - please re-read the kiosk-compatibility constraint first. We've been here.

Related code

• src/CapyBro/Platform/SingleInstance.cs - implementation
• Local\CapyBroV2.Activate - paired EventWaitHandle for cross-instance signaling

Future consideration

If we add an admin-install variant (alongside the per-user install), we COULD use Global\ for that variant. But maintaining two binary configurations is overhead - punt until there's real demand.