Help

These are the questions that come up most often during setup. If yours is missing, write to info@paperlesschat.app.

Set up Paperless AI

Paperless Chat uses the AI built into your Paperless-ngx, which needs Paperless-ngx 3.0 or later. An admin turns on AI in the Paperless configuration, picks a language model, for example through Ollama or an OpenAI-compatible API, and a model for embeddings. Paperless then builds an index of your documents. Only once that is done does the chat find matching documents.

The configuration page of the Paperless docs describes each setting.

If you are an admin, you can also change the AI settings in the app under Settings › Paperless AI. Before saving, the app shows you every change. The changes apply to everyone on your Paperless server.

If the app says “AI is turned off on your Paperless server.”, AI has not been turned on in Paperless yet.

Find your token

Open the Paperless web interface and click your username in the top right corner. Your profile shows the API token. Generate one there if none exists yet, and copy it. In the app, choose “API token” when you sign in and paste it.

A token has the same permissions as your user. If you generate a new one, the old one stops working right away and you sign in again in the app.

Two-factor sign-in

If you sign in with username and password and two-factor authentication is on in Paperless, the app asks for the six-digit code from your authenticator app. After that it continues with a token and does not store your password or the code.

Paperless allows only five sign-in attempts per minute. If the app reports too many attempts, wait a minute. You can also sign in with a token, which needs no code.

Recovery codes do not work when you sign in to the app with your password; the app only accepts the code from your authenticator app. If all you have left is a recovery code, use it to sign in to the Paperless web interface, create an API token there (see Find your token) and sign in to the app with that token.

Self-signed certificates

If your server has a self-signed or unknown certificate, the app shows the issuer and the SHA-256 fingerprint. Compare it with the certificate on your server, for example like this:

openssl x509 -noout -fingerprint -sha256 -in certificate.pem

Only after you confirm does the app trust exactly this certificate and no other. If the fingerprint changes later, for example after a renewal, it asks again.

On your home network a plain http connection works too. The app then keeps showing the notice “Unencrypted connection”.

Proxy sign-in and extra headers

If your Paperless sits behind its own sign-in, such as Authelia, Authentik, oauth2-proxy or Cloudflare Access, the app gets a login page instead of Paperless. The app does not support signing in through a web page yet. It can, however, send extra headers with every request so that your proxy lets it through. You add them under Connection › Advanced.

Example: Cloudflare Access

  1. Create a service token in Cloudflare Zero Trust. You get a client ID and a client secret.
  2. Add a policy with the action “Service Auth” that allows this service token to the Access application for your Paperless server.
  3. Add two extra headers in the app:
CF-Access-Client-Id: <client ID>
CF-Access-Client-Secret: <client secret>

The app stores extra headers encrypted and sends them only to your server, including requests for thumbnails and documents.

Basic auth at the proxy

If your proxy asks for a username and password through Basic auth, enter them under Connection › Advanced as proxy user and proxy password. The app sends them as Proxy-Authorization. Many reverse proxies expect Basic auth in the Authorization header, though, and Paperless needs that header for the token. In that case, exempt the path /api/ from Basic auth or use extra headers.

The app does not support client certificates (mTLS) yet.

Answers arrive all at once instead of bit by bit

Paperless sends the answer piece by piece while the model writes it. If a reverse proxy buffers the response, the answer only arrives once it is complete. With nginx, turn off buffering by adding these lines to the existing location block that proxies Paperless:

proxy_buffering off;
proxy_read_timeout 300s;

Do not create a new location block for this. nginx does not carry the proxy_set_header lines over from other blocks, and without the right Host header Paperless rejects the requests. The second line is optional: it keeps nginx from giving up after 60 seconds without data when the model is slow. Reload nginx afterwards, for example with nginx -s reload.

Other proxies have their own setting for this. Traefik, for example, only buffers when the buffering middleware is active.

The chat does not know my previous question

Paperless answers each question on its own. It keeps no memory of the conversation, and the app does not pretend otherwise. A follow-up such as “and the year before?” therefore makes no sense to Paperless.

Ask the full question, or tap “Edit question” on the last one and change it. To ask about one specific document, open it and choose “Ask about this document”.

Read aloud and voice input

You can have every finished answer read aloud, on iOS and Android. The app uses your device’s voices. On Android, “Read aloud” only appears when a voice that works without a network connection is installed. You can add voices in the system settings under text-to-speech.

On iPhone and iPad you can also speak your questions. Tap the microphone in the empty input field. Recognition runs only on the device. From iOS 26, the system may download a language pack for it once. If your device cannot recognise the language without a server, the app hides the microphone. On Android, voice input arrives with version 1.1; until then, use your keyboard’s dictation.

Contact

Write to info@paperlesschat.app. It helps to include the app version, your device, the Paperless version and whether a proxy sits in front of it. Please never send us tokens, passwords or documents from your archive.