KumoPermissions
When macOS asks for elevated privileges, and what Kumo deliberately does not do.
The first version of Kumo intentionally avoids privileged helpers. macOS asks for administrator authorization in a few narrowly scoped situations and nothing else.
What Kumo does not do
- It does not register a NetworkExtension.
- It does not register a VPN profile.
- It does not ask for the Allow VPN Configuration prompt.
System proxy uses networksetup, the same tool available from the
command line. TUN uses the standard macOS utun* device.
When Kumo asks for admin
| Action | What macOS prompts for |
|---|---|
Installing or removing /usr/local/bin/kumo symlink | /usr/local/bin requires elevated privileges. |
| Installing or repairing the Kumo Helper (planned) | LaunchDaemon installation. |
| Installing or removing the Kumo Helper LaunchDaemon | Same as above. |
Each prompt is one-shot — Kumo runs
osascript ... with administrator privileges once per operation.
Approving the prompt does not grant Kumo ongoing root.
Entitlements
The app bundle ships with these entitlements:
- App Sandbox — disabled in v1. Spawning Mihomo and Sub-Store
as child processes plus invoking
networksetupis incompatible with the sandbox's restrictions onProcessand shell-out. App Sandbox plus helper-bundle separation is on the roadmap. - Network client — enabled. Required for the Mihomo controller and for fetching subscription URLs.
- Network server — enabled. Required for the PAC HTTP listener and for Mihomo's external-controller endpoint.
Info.plist declares the usage strings under
NSAppleEventsUsageDescription and
NSSystemAdministrationUsageDescription for the rare moments an
authorization prompt does appear.
Service mode (planned)
When the Kumo Helper service mode ships, macOS will ask for administrator authorization at install / uninstall time, the same way Sparkle and Clash Verge Rev do. The helper will own privileged operations such as TUN control, guarded system proxy changes, and notarized auto-update.
Until then:
- TUN enable requests fail with a visible service-mode error rather than leaving the UI in a misleading "On" state.
- System proxy changes still work without the helper, because Kumo can
run
networksetupitself.
Permission FAQ
Why is Kumo not sandboxed?
v1 ships with the sandbox disabled because spawning Mihomo and
Sub-Store as child processes is incompatible with the sandbox's
restrictions on Process and networksetup. App Sandbox plus
helper-bundle separation is on the roadmap.
Why does Kumo not ask for "Allow VPN Configuration"?
That prompt is for NetworkExtensions. Kumo uses system proxy and TUN directly, so it does not trigger the prompt.
What runs as root?
Nothing in Kumo runs as root in v1. The only
with administrator privileges shell calls are short-lived ln /
rm invocations during CLI symlink install / uninstall.
If something else asks for root, verify what is actually triggering it. Kumo's prompts always come from the Kumo application (visible in the auth dialog).