How to Use paperless-ai: The Beginner's Guide (First Install, the API-Token Rule, Auto-Tagging, and RAG Chat)

CodexFuse Team · 2026-11-02T06:59:51.799Z · 13 min read min read

Learn how to use paperless-ai, the AI companion for Paperless-ngx: install with Docker, connect with an API token, run automatic tagging, chat with documents via RAG, and choose between local and cloud AI.

Learning how to use paperless-ai starts with one sentence: paperless-ai is an AI-powered extension for Paperless-ngx that automatically analyzes your scanned documents, assigns them titles, tags, document types, and correspondents, and then lets you ask questions of your whole archive in plain language. If your Paperless-ngx already eats every receipt, contract, and utility bill you throw at it, this paperless-ai tutorial walks the full beginner arc: install with Docker, connect it to Paperless-ngx with an API token (the step that blocks almost everyone once), run your first automatic tagging pass, chat with your documents through RAG, and pick between a local or cloud AI model. The install assumes you have a working Paperless-ngx; if you are still setting that up, my paperless-ngx beginner guide goes from zero to your first document, and my Docker beginner guide covers the container basics this guide leans on.

Two honest facts before the steps. First, at the time I checked this week, the clusterzx/paperless-ai repository had 5,988 stars and 331 forks and is released under the MIT license — but the maintainer's own README currently says the project is not actively maintained (there is a full, fair section on that below, including the maintained fork). This guide teaches the software as it runs today, because thousands of self-hosters still run it. Second, paperless-ai CHANGES your documents — the Marius Hosting guide, updated September 28, 2026, warns verbatim: "Paperless-AI makes changes to the documents in your productive PaperlessNGX instance that cannot be easily undone. Do the configuration carefully and think twice." Back up before you integrate.

What Is paperless-ai, Exactly?

paperless-ai is an automated document analyzer for Paperless-ngx. The repo's own description says it all: "An automated document analyzer for Paperless-ngx using OpenAI API, Ollama, Deepseek-r1, Azure and all OpenAI API compatible Services to automatically analyze and tag your documents." Under the hood it is a Node.js web app with a Python RAG backend, shipped as a Docker container, and it does three jobs: it detects new documents in Paperless-ngx automatically and tags them, it offers a manual tagging desk for files you want to review yourself, and it gives you a RAG chat that answers questions across your whole archive with source citations. The paperless-ngx wiki's Related Projects page lists it verbatim: "An automated document analyzer for Paperless-ngx using OpenAI API to automatically analyze and tag your documents and add correspondents."

The one thing it is NOT: paperless-ai is not a document system itself. Paperless-ngx is the document system — scanning, OCR, storage, the consume folder. paperless-ai is the AI companion that sits next to it and does the reading for you. (It is also not paperless-gpt, a different tool — the one-paragraph contrast lives below, said once.)

What Do You Need Before You Install It?

Four things, all cheaper to settle now than mid-install. First, a reachable Paperless-ngx instance — paperless-ai does not store documents itself; it reads and writes to yours. Second, Docker 20.10+ with Docker Compose 2.0+, and a machine with at least 2 GB of RAM (4 GB+ if your archive is large). If you have not chosen a server yet, what is VPS hosting explains the kind of machine these guides assume. Third, your model decision: a local Ollama model (private, free, slower) or a cloud provider's API key (fast, per-token cost, your documents leave your network). Fourth, a full backup of your Paperless-ngx data — see the Marius warning above.

How Do You Install paperless-ai with Docker?

The canonical paperless-ai docker install is the official clusterzx/paperless-ai image on Docker Hub, started with Compose. The environment variables below are the day-one essentials, assembled from the project's Docker Hub page and the fresh ZimaOS install guide from October 29, 2026:

PAPERLESS_AI_PORT=3000
RAG_SERVICE_ENABLED=true
RAG_SERVICE_URL=http://localhost:8000
PUID=999
PGID=1000

1. Pull the image: clusterzx/paperless-ai:latest — always the plain project image, not a random fork.
2. Mount the two volumes: /app/data and /var/lib/paperless-ai hold the database and the RAG index — bind them to host paths so nothing vanishes on container recreation.
3. Set the five env vars above: the web UI listens on PAPERLESS_AI_PORT (3000 by default); RAG_SERVICE_URL defaults to the internal RAG backend at http://localhost:8000 — leave it alone unless you moved the RAG container.
4. Get PUID and PGID right on the first try: these set the file ownership paperless-ai writes with. The ZimaOS guide is blunt: "These values determine the system permissions Paperless-AI will use. If they are incorrect, you may experience issues with tagging, renaming, or file management that require a full reinstall to fix." Find them with id -u username and id -g username on the host.
5. Start it and open the UI: http://your-server:3000 shows the setup wizard.
6. Answer the automatic-processing question: after you save the setup, the wizard asks about automatic document processing — the ZimaOS guide quotes the prompt and the rule: "If prompted about automatic document processing, click 'Yes, Continue.' Paperless-AI will restart and begin analyzing documents from Paperless-NGX."

The API-Token Rule: Nothing Works Until You Paste It

One line of context before the token steps: a paperless-ai setup is really two connections — the container-to-Paperless-ngx API token (below) and the container-to-RAG-backend URL (the internal default from the env table). Get both right and the rest is downhill.

The single most common paperless-ai failure is a container running perfectly with zero documents processed — because it never got a valid Paperless-ngx API token. Say it once: nothing processes until the token connection test passes. Making the token takes thirty seconds in Paperless-ngx. The Marius Hosting guide gives the path verbatim: "On the left sidebar, click on your name, then My Profile... On the API Auth Token area, click the refresh icon, then Copy the auto-generated token in a safe place. You will need this token later." Then open paperless-ai's setup wizard at /setup, go to Connection Settings, and paste the token next to your Paperless-ngx API URL — with no trailing slash on the URL. The wizard's connection tab then tests connectivity against the /api/documents/ endpoint and validates permissions across documents, correspondents, tags, document types, custom fields, and users. Until that check passes, the tagging engine sits idle no matter how healthy the container looks.

How Does Automatic Tagging Work?

paperless-ai automatic tagging kicks in once the token is accepted: the engine reads each document's content and returns structured metadata. The README describes the assignment verbatim: paperless-ai "Assigns title, tags, document type, and correspondent" and "Detects new documents in Paperless-ngx automatically." A scanned electricity bill comes back as title "Electricity Bill — March", tag "utilities", document type "Bill", correspondent "Power Company" — and the change lands in your real Paperless-ngx archive, which is why the backup warning from earlier matters.

On the scale question: the ZimaOS author's real-world run is the datum we have — verbatim: "I processed nearly 9,000 documents on my Zimaboard 2. The full process took around 3 days." Local models on modest hardware are slow; that is normal, not broken. One practical touch from the Marius guide's advanced settings: set the AI-processed tag name (default ai-processed) so you can always see which documents the AI touched.

How Do You Chat with Your Documents?

paperless-ai chat with documents is the tool’s second half — semantic search plus multi-document question answering, powered by the RAG backend you enabled at install. The setup arc runs like this:

1. Restart the container after setup: the README says it plainly — "Restart the container after completing setup (API keys, preferences) to build RAG index."
2. Open RAG Chat and start indexing: the flow is "Go to RAG Chat and click 'Start indexing'", and success looks like "RAG indexing completes successfully (N documents indexed)" — ChromaDB and BM25 indices built over your archive.
3. Ask in plain language: the README's own example questions show the intent: "When did I sign my rental agreement?", "What was the amount of the last electricity bill?", "Which documents mention my health insurance?" Answers arrive with source citations pointing back at the real documents.
4. Understand what it is not: this is semantic search over your archive, not a general chatbot — it only knows what you have scanned.

How it finds answers in one paragraph: the search is hybrid — BM25 keyword matching counts for 30% and semantic vector search counts for 70%, with cross-encoder reranking on top, defaulting to hybrid mode. That is why a question about "the power bill" can find a document titled "Invoice — Municipal Utilities" without sharing a single word.

Local or Cloud: Which AI Model Should You Pick?

The paperless-ai ollama path is what makes the privacy question real — this is the one section where the privacy-versus-speed tradeoff lives — the rest of the guide stays model-agnostic. Provider support, verified against today's README: Ollama (Mistral, Llama, Phi-3, Gemma-2), OpenAI, DeepSeek.ai, OpenRouter.ai, Perplexity.ai, Together.ai, LiteLLM, VLLM, Fastchat, Gemini (Google), "...and more!" The setup UI's provider options are openai, ollama, azure, and custom. There is no documented default model — the ZimaOS author, testing in October 2026, recommends: "choose Custom as the AI Provider and manually set both the Base URL and Model. I tested OpenAI, Mistral AI, and Google Gemini; all worked flawlessly."

Whichever you choose, run the web UI on your local network only — the guides agree the API-key handling is not something to expose to the internet.

paperless-ai vs paperless-gpt: What's the Difference?

These are two different tools with confusingly similar names, so here is the line, drawn once: paperless-gpt (icereed/paperless-gpt) is a tag-triggered pipeline that lives inside Paperless-ngx's workflow system — you attach tags like paperless-gpt, paperless-gpt-auto, or paperless-gpt-ocr-auto to documents and it processes them, with its signature strength being vision-LLM OCR. The fariszr piece describes it verbatim: "with Paperless-GPT you can use it to OCR documents using vision LLM models, using cloud vision models like GPT-4o, custom services from Google and Azure or even using local open source LLMs!" paperless-ai is instead a standalone web app with its own UI: automatic and manual tagging modes plus the RAG chat across your archive. Different products, never rivals — this guide is only about paperless-ai.

The Honest Maintenance Note

Now the caveat this guide promised. The README carries an IMPORTANT NOTICE, verbatim: "This repo is currently not maintained... I'm currently rewriting the entire codebase with a more stable, up-to-date architecture... With the upcoming official AI integration in Paperless-ngx itself, I'm also not sure if I'll complete the rewrite or continue maintaining this repo at all." What that means in practice: the software runs fine today — thousands of installs, a 5,988-star track record — but bugs may not get fixed and the RAG stack is aging. There is also a maintained community fork, admonstrator/paperless-ai-next (updated June 2026), which deliberately removed RAG/chat — the fork's author explains the old secondary Python container "added massive image sizes, high RAM requirements, and severe architectural overhead" — to focus on tagging and correspondent detection, adding vision OCR, MFA, and rate limiting; the same author warns there is "no guarantee of stability right now." So: want RAG chat over your archive today, install paperless-ai; want active maintenance, watch the fork and the coming official Paperless-ngx AI integration. And do not let any blog — this one included — promise you a CodexFuse-hosted paperless-ai tool: none exists.

7 Mistakes Beginners Make with paperless-ai

Sources

1. clusterzx/paperless-ai on GitHub (project description, one-sentence README, 5,988 stars / 331 forks snapshot, MIT license, auto-tagging modes, RAG chat examples, unmaintained IMPORTANT NOTICE)
2. ZimaOS — paperless-ai Install (install guide, October 29, 2026: env vars, PUID/PGID quote, 9,000-document / 3-day datum, Custom provider recommendation)
3. Marius Hosting — Install paperless-ai on Synology NAS (updated September 28, 2026: mandatory-changes warning verbatim, API token path verbatim, ai-processed tag, Ollama-on-NAS warning, v3.0.9)
4. Admin Intelligence — paperless-ai on Synology NAS (capabilities, auto-tagging flow, privacy framing, resource caveats)
5. AiShareNet — paperless-ai (independent intro with Using Help; older env-var-era docs, used for contrast only)
6. DeepWiki — paperless-ai Installation & Setup (env var defaults, RAG_SERVICE_URL default, Docker/Compose/RAM prerequisites)
7. DeepWiki — RAG System (hybrid BM25 30% + semantic 70%, cross-encoder reranking, index files)
8. DeepWiki — RAG Chat Interface (chat flow)
9. DeepWiki — Initial Configuration (fork docs) (setup wizard, connection test and endpoint validation)
10. Docker Hub — admonstrator/paperless-ai-next (maintained fork: RAG removed for overhead, vision OCR, stability warning)
11. Fariszr — Go Paperless with AI (paperless-gpt description, vision-OCR quote, tag-triggered pipeline)
12. paperless-ngx Wiki — Related Projects (paperless-ai listing quote)
13. The Paperless Agent — Pre-Listing Packet GPT Tutorial (name-dilution note only: a real-estate GPT tool, unrelated to paperless-ai)

Frequently Asked Questions

Is paperless-ai free?

Yes — it is MIT-licensed open source, so self-hosting costs only the server. If you use a cloud AI provider, you pay that provider's per-token rates; a local Ollama model is free but slower, especially on a NAS.

Does paperless-ai work without Paperless-ngx?

No. paperless-ai is a companion, not a document system — it reads from and writes to your Paperless-ngx archive through its API. No Paperless-ngx, nothing to analyze.

Why are my documents not being processed?

Almost always the API token. Check that the token is fresh (regenerate it in Paperless-ngx under My Profile), the API URL has no trailing slash, and the setup wizard's connection test passes its endpoint validation. Then confirm you answered "Yes, Continue" on the automatic-processing prompt so the engine actually started.

Can I use paperless-ai with a fully local model?

Yes — the Ollama provider keeps document content on your machine. Budget for slower tagging and indexing, and do not run a large model on a low-power NAS unless you are patient: 9,000 documents took about three days on a Zimaboard 2 in the documented real-world run.

Should I still install paperless-ai if it is unmaintained?

For RAG chat over your archive today, it is still the working option — thousands of installs run it fine. But go in with eyes open: bugs may not be fixed. If active maintenance matters more to you than chat, watch the admonstrator/paperless-ai-next fork and the upcoming official Paperless-ngx AI integration instead.