Skip to content

paperless-secretary

paperless-secretary is a self-hosted Docker service that automatically processes and enriches your Paperless-ngx documents using a declarative YAML rules engine.

Instead of manually tagging, renaming, or classifying every document, you write rules that run automatically whenever a document is created or updated. Rules can match content with regex, set fields, add/remove tags, write custom fields, and much more — all without modifying Paperless-ngx itself.

How it works

sequenceDiagram
    participant P as Paperless-ngx
    participant S as Secretary
    participant PApi as Paperless API

    P->>S: POST /api/webhook/paperless<br/>(document_added / document_updated)
    S->>S: Match triggers & filters
    S->>S: Evaluate conditions
    S->>PApi: Fetch document details
    S->>S: Execute actions
    S->>PApi: PATCH document (save)
  1. Paperless-ngx sends a webhook event when a document is added or updated.
  2. Secretary evaluates every loaded rule against the event.
  3. Rules that match have their actions executed against the live Paperless document.
  4. Changes (field updates, tags, notes) are written back via the Paperless-ngx API.

Key features

  • Declarative YAML rules — version-controllable, human-readable automation
  • Rich DSL — triggers, filters, conditions (field / classifier / variable / template / logical operators), and 11 action types
  • Jinja2 templating — dynamic values and a shared _vars.yml file for reusable data
  • Dry-run mode — test any rule against real documents without applying changes
  • Hot-reload — edit rule files and changes take effect immediately, no restart needed
  • Multiple entrypoints — Paperless-ngx webhook, REST API, and optional MQTT broker
  • Built-in Web UI — rule editor, dry-run runner, execution history, live log stream
  • SQLite history — all executions are stored and automatically purged

Project layout

paperless-secretary/
├── backend/          # Python / FastAPI service
│   └── secretary/
│       ├── core/     # Rules engine (compiler, dispatcher, engine, runtime)
│       ├── dsl/      # YAML DSL models (Rule, Trigger, Condition, Action)
│       ├── entrypoints/  # Webhook, REST API, MQTT, WebSocket
│       └── services/ # Loader, watcher, DB, Paperless client
├── frontend/         # Vue 3 + TypeScript web UI
└── rules.d/          # Your rule files go here

Get started →