Overview
Paperless Starfruit is a self-hosted, bring-your-own-keys AI companion for paperless-ngx. It adds the two things paperless can’t do on its own: higher-quality OCR and automatic metadata (a clean title, tags, correspondent and date for every document you tag).
Everything is configured from the web UI; the only outside setup is a handful of environment variables for the process itself.
How it fits
Section titled “How it fits”It runs as a second container beside paperless-ngx and talks to it over the same REST API you already use. It never touches your library directly: it reads the documents you tag, asks the AI models you connect for metadata, and writes the result back.
The ideas to know
Section titled “The ideas to know”- One trigger tag. Add
psf-processto a document and it gets picked up. Re-tag to reprocess; leave it untagged and it is never touched. - OCR is optional. Re-read the original with a vision model, or reuse the free text paperless already extracted. Extraction runs on that text either way.
- Extraction is one call. A single language-model request returns a title, tags, correspondent and date, validated against a strict schema. Vision-capable models also see the original document: letterheads and signatures beat a garbled text layer.
- You decide how it applies. Auto-apply writes changes straight back to paperless; turn it off and every suggestion waits in the review queue for your approval.
- Single container, single admin. A Node process and a SQLite file: no Postgres, no Redis. On first run you create one admin account.
Start here
Section titled “Start here”InstallationPull the official image and deploy with Docker Compose.
Connect paperlessPoint it at your instance and set up the trigger tag.
AI providers & keysAdd the providers you want to use for OCR and extraction.
How processing worksFollow a document through the pipeline, step by step.