> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenpipe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# fix screen recording permission on macos for screenpipe

> Grant, reset, and recover macOS Screen Recording permission for screenpipe — covers per-bundle-id TCC, tccutil commands, and System Settings steps.

{/* https://screenpi.pe */}

screenpipe needs macOS Screen Recording permission to capture frames and run OCR on what you see. if the engine fails to start with a permission error — including the "engine stuck" screen during onboarding — this page walks through every recovery path.

## grant it (the normal path)

1. open **System Settings** → **Privacy & Security** → **Screen & System Audio Recording**.
2. toggle **screenpipe** ON. macOS will prompt you to quit and reopen — click **Quit & Reopen**.
3. restart screenpipe. the engine should start within a few seconds.

the in-app "open system settings" button on the stuck screen jumps straight to this pane.

## if you switched build channels

macOS's TCC database (transparency, consent & control) tracks Screen Recording permission **per bundle id**, not per app name. if you previously granted permission to one build and switched to another, the new build looks like a brand new app to macOS — your earlier grant doesn't apply.

screenpipe ships under four bundle ids:

| bundle id                | channel                                     |
| ------------------------ | ------------------------------------------- |
| `screenpi.pe`            | production (stable release)                 |
| `screenpi.pe.beta`       | beta channel                                |
| `screenpi.pe.dev`        | local dev build (`cargo` / `bun tauri dev`) |
| `screenpi.pe.enterprise` | enterprise distribution                     |

the stuck screen shows which one you're running as. if it doesn't match the entry you've toggled in System Settings, you need to grant permission for the new bundle id.

this is the single most common cause of "engine stuck" during onboarding — confirmed by telemetry showing 90% of stuck users have no boot phase reported, which is exactly the signature of a permission rejection at spawn time.

## reset and re-request

when the permission is in a wedged terminal state — screenpipe shows in System Settings but toggling does nothing, or it doesn't show at all — wipe the TCC record for that bundle id and re-trigger the prompt.

the in-app **reset & re-request** button does this for you. it runs:

```bash theme={null}
tccutil reset ScreenCapture <your-bundle-id>
```

you can run it manually from Terminal too. for each bundle id you have installed:

```bash theme={null}
# production build
tccutil reset ScreenCapture screenpi.pe

# beta channel
tccutil reset ScreenCapture screenpi.pe.beta

# local dev build
tccutil reset ScreenCapture screenpi.pe.dev

# enterprise distribution
tccutil reset ScreenCapture screenpi.pe.enterprise
```

no sudo required — TCC's per-app records live in your user scope.

after reset, relaunch screenpipe. macOS will prompt fresh.

## nuclear option

if per-bundle resets don't recover, wipe every app's Screen Recording grant in one shot:

```bash theme={null}
tccutil reset ScreenCapture
```

this affects every screen-recording app on your machine (zoom, OBS, cleanshot, etc.) — they'll all re-prompt on next launch. only use this if the scoped resets above failed.

## related permissions

screen recording is the most failure-prone, but screenpipe also asks for:

* **microphone** — for audio capture. System Settings → Privacy & Security → Microphone. reset: `tccutil reset Microphone <bundle-id>`
* **accessibility** — for app/window context. System Settings → Privacy & Security → Accessibility. reset: `tccutil reset Accessibility <bundle-id>`
* **input monitoring** — for keystrokes (optional). System Settings → Privacy & Security → Input Monitoring. reset: `tccutil reset ListenEvent <bundle-id>`

the same per-bundle-id rules apply to all of these.

## still stuck?

send logs from the stuck screen (the **send logs** button uploads them so the team can grep). or book a slot at [cal.com/team/screenpipe/chat](https://cal.com/team/screenpipe/chat).

see also: [general troubleshooting](/troubleshooting), [FAQ](/faq).