macOS Permissions

Stellar needs only a few system permissions on macOS. This page lists the permissions Stellar actually needs, the ones it does not need (but are often granted by mistake), and where to toggle each.

TL;DR

If you've seen advice on the web suggesting you grant Stellar "Full Disk Access," do not follow it. A VPN client doesn't need that, and granting it exposes your Mail, Messages, Safari history, and other private data to a network tool.

Permissions Stellar needs

1. Background / Login Items

What it does: Stellar's privileged helper daemon is registered via macOS's SMAppService. This permission is what lets it start in the background when you log in. This is the actual cause of most "can't connect" errors.

Where to grant:

System Settings → General → Login Items → "Allow in the Background"

Find Stellar in the list and make sure its switch is on.

2. Network Extension / VPN

What it does: Stellar creates a TUN virtual interface to route system traffic. macOS prompts you to authorize this at install time — once approved, you don't need to do anything else.

Where to grant: Usually nothing to do — just click "Allow" on the install-time prompt. If you previously clicked "Deny":

System Settings → Privacy & Security → scroll down to find Stellar and re-allow.

3. Notifications (optional)

What it does: Desktop notifications when connection state changes. Connection works fine without this — purely optional.

Where to grant:

System Settings → Notifications → Stellar

❌ Permissions Stellar does NOT need

If any of these are toggled on for Stellar, you can turn them off:

| Permission | Why Stellar doesn't need it | |---|---| | Full Disk Access | A VPN doesn't read Mail, Messages, or Safari data. Granting it gives the client access to all of that. | | Accessibility | Stellar doesn't simulate keyboard/mouse or control other apps' windows. | | Screen Recording | Stellar doesn't read your screen. | | Microphone / Camera | Completely unrelated. | | Files and Folders access | Stellar only reads its own config, no extra folder permissions required. |

If you previously enabled Stellar / Stellar Helper / sfltool under System Settings → Privacy & Security → Full Disk Access, turn it off.

What about the "BTM repair" dialog?

If Stellar shows a dialog like "Re-install Stellar Helper" or "Repair macOS Background Task State" on startup, macOS's SMAppService registration is stuck (commonly called BTM corruption). This has nothing to do with disk access permissions.

The right order to try things:

  1. First choice: click Install Helper (Legacy) — uses the older SMJobBless path. One admin password prompt, no reboot. This fixes it in almost every case.
  2. Fallback: click Fix macOS Background Task State — runs sudo sfltool resetbtm and requires a reboot.
  3. Don't do: don't grant Full Disk Access, don't run shell commands manually unless you know exactly what you're doing.

Still can't connect?

Open Settings → Contact Us and include:

  1. The line name you're connecting to
  2. Which mode you're using (HTTP / Computer mode / TUN)
  3. A screenshot or log (logs live at ~/Library/Logs/Stellar/)

We'll diagnose based on actual data instead of guessing which permissions to flip.