pipe permissions

overview

pipes can access the screenpipe API to read screen data, manage meetings, send notifications, and more. by default, pipes have full access to every endpoint — no restrictions.

if you want to limit what a pipe can do, add a permissions block to the YAML frontmatter in pipe.md. this is useful for:

• preventing accidents — a pipe that reads meetings shouldn't be able to stop one
• least privilege — pipes from the store should only access what they need
• safety — deny destructive endpoints like /data/delete-range

quick start

---
schedule: every 30m
permissions: reader
---

Summarize my screen activity...

that's it. this pipe can only read data — it can't start/stop meetings, delete data, or run raw SQL.

presets

reader — safe read-only defaults

permissions: reader

allowed endpoints:

everything else is denied.

writer — reader + write operations

permissions: writer

includes all reader endpoints, plus:

admin — full access (explicit)

permissions: admin

allows everything. functionally the same as no permissions block, but creates a token for logging/auditing.

custom rules

for fine-grained control, use allow and deny lists with Api(METHOD /path) patterns:

permissions:
  allow:
    - Api(GET /search)
    - Api(GET /meetings/*)
    - Api(POST /notify)
  deny:
    - Api(* /data/delete-*)

pattern syntax

* in the method position matches GET, POST, PUT, DELETE, etc. * in the path position matches any sequence of characters.

evaluation order

rules are evaluated in this order — first match wins:

1. deny — if the request matches any deny rule, it's blocked (403)
2. allow — if the request matches any allow rule, it passes
3. default allowlist — if allow is empty and the pipe uses a preset with defaults (reader/writer), the default list is checked
4. reject — if nothing matched, the request is blocked

deny always wins over allow, just like firewall rules.

examples

deny specific endpoints (keep full access otherwise):

permissions:
  deny:
    - Api(* /meetings/stop)
    - Api(* /meetings/start)
    - Api(DELETE /meetings/*)
    - Api(* /data/delete-*)

allow only what you need (everything else denied):

permissions:
  allow:
    - Api(GET /search)
    - Api(POST /notify)

reader defaults + custom deny:

permissions:
  deny:
    - Api(GET /frames/*)

this uses the reader defaults but also blocks screenshot access.

data access rules

data filtering uses the same allow/deny lists with App(), Window(), and Content() rules:

---
schedule: every 1h
permissions:
  allow:
    - Api(GET /search)
    - App(Slack, Chrome)
    - Window(*meeting*)
    - Content(ocr, audio)
  deny:
    - App(1Password, Signal)
    - Window(*incognito*, *bank*)
    - Content(input)
  time: "09:00-17:00"
  days: "Mon,Tue,Wed,Thu,Fri"
---

deny rules always win over allow rules. if no rules of a given type exist, everything is allowed.

how it works

when a pipe has any restrictions (permissions block, data filters, etc.):

1. screenpipe generates a unique token (sp_pipe_*) for the pipe session
2. the token is registered with the server middleware
3. every API request from the pipe includes the token in Authorization: Bearer sp_pipe_*
4. the middleware checks is_endpoint_allowed(method, path) before forwarding
5. the Pi extension also enforces rules client-side (blocks curl commands before they run)
6. when the pipe finishes, the token is cleaned up

pipes without any restrictions run without a token — full access, zero overhead.

common recipes

meeting-safe pipe

your pipe reads meeting data but should never interfere with active meetings:

---
schedule: every 1h
permissions:
  deny:
    - Api(* /meetings/start)
    - Api(* /meetings/stop)
    - Api(POST /meetings/merge)
    - Api(POST /meetings/bulk-delete)
    - Api(DELETE /meetings/*)
---

Summarize my meetings from the last hour...

read-only analytics pipe

---
schedule: daily
permissions:
  allow:
    - Api(GET /search)
    - App(Chrome, Arc, Firefox)
    - Content(ocr)
---

Generate a daily browsing report...

work-hours-only pipe

---
schedule: every 30m
permissions:
  time: "09:00-17:00"
  days: "Mon,Tue,Wed,Thu,Fri"
---

Track my work activity...

full API access, but time and day restrictions limit when data is visible.

need help? ask in our discord