Connect paperless

Open Settings → Connection and link your paperless-ngx instance.

1. Enter the base URL of your paperless instance, e.g. https://paperless.home.lan. If both run in the same Docker network, use the service name instead of localhost (see Installation).

2. Paste an API token. In paperless, mint one under Settings → My Profile → API Auth Token.

3. Test connection. A read-only check confirms the URL and token and reports the server’s API version and document count. Leave API version blank; it is auto-detected.

4. Save. The token is stored encrypted at rest and never returned to the browser again.

Use a least-privilege user

Prefer a dedicated paperless user over the superuser: create an account that can view and change documents and view and add tags and correspondents, then mint that user’s token. Paperless Starfruit only reads documents you tag and writes back metadata. It needs nothing more.

Why URLs aren't SSRF-restricted

This app must reach self-hosted and LAN addresses (paperless on a private IP, a local Ollama), so admin-entered URLs are intentionally not blocked from reaching internal hosts. The security model is one trusted admin.

The trigger tag

Processing is driven by a single tag: psf-process.

• Tag a document (by hand, or with a paperless rule) and the poller picks it up on its next cycle.
• Re-tag to run it again. This is the explicit “process me” signal.
• Untagged documents are never read or modified.

When a result is applied, the trigger tag is removed in the same update that writes the metadata, so the document won’t be picked up again unless you re-tag it. Whether results apply automatically or wait for your review is the Auto-apply setting; see Processing.

Next

Add your AI providers and keys →