# Docspell

Document organizer with OCR, NLP metadata suggestions, HOCON config, a full REST API, and the dsc CLI.

Docspell ingests scans, email attachments, and uploads, runs OCR, suggests correspondents, tags, and dates with Stanford CoreNLP, and stores everything with custom fields and full-text search. It targets households and smaller companies. Two Scala services (restserver and joex) are configured with HOCON files or env vars; every feature is reachable over the REST API, which the dsc CLI and Android app use.

- Capabilities: adaptable, operable
- Vertical: support-bookkeeping
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/eikek/docspell (AGPL-3.0), 2317 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/eikek--docspell.html
- JSON: apps/eikek--docspell.json

## Use it when

- we scan supplier invoices and receipts and want them OCR'd, dated, and matched to the right vendor automatically before the bookkeeper sees them
- we want our agent to push documents in through the integration endpoint and search them by vendor and date range

## Gotchas

- AGPL-3.0 or later
- JVM plus tesseract, ocrmypdf, unoconv; the joex worker is memory-hungry with NLP enabled
- Session tokens default to 5 minutes; long agent sessions must renew through /sec/auth/session
- Positioned for home and small groups; multi-tenant is by collective, not by organization hierarchy

## Editions

- Free (self-hosted): Free, open source
  - source: https://github.com/eikek/docspell
  - container: git clone https://github.com/docspell/docker docspell-docker && cd docspell-docker/docker-compose && docker-compose up -d
  - binary: https://github.com/eikek/docspell/releases

## Adaptable: make it yours

Effort: config-only (9 things to edit)

Two HOCON files (docspell.server.* and docspell.joex.*) or env vars in the DOCSPELL_SERVER_APP__NAME pattern. An SMB sets docspell.server.base-url, backend.signup.mode (closed after the first collective), backend.jdbc, full-text-search backend, joex OCR languages and ocrmypdf options, the integration-endpoint secret for scanner uploads, and SMTP for outgoing mail. Correspondents, tags, custom fields, and scan-mailbox jobs are created in the app.

- Env vars: DOCSPELL_SERVER_APP__NAME, DOCSPELL_SERVER_BASE__URL, DOCSPELL_SERVER_BACKEND_SIGNUP_MODE, DOCSPELL_SERVER_BACKEND_JDBC_URL, DOCSPELL_JOEX_BASE__URL
- Config files: docspell-server.conf, docspell-joex.conf, modules/restserver/src/main/resources/reference.conf, modules/joex/src/main/resources/reference.conf
- Prompt files: none
- Accounts you'll need: none; optional SMTP and IMAP mailboxes

## Operable: what an agent can drive

Operability: official. Interface: api at https://docspell.org/docs/api/ (published by the builder, local).

### Reach (partial coverage)

- Upload documents: reachable. docs/api: upload request; integration endpoint and source URLs for unauthenticated uploads; dsc CLI watch and upload
- Search with the query language: reachable. docs/api/intro: protected route /sec/item/search
- Edit tags, correspondents, custom fields, dates: reachable. README: everything is accessible through a REST/HTTP api; web app is a client of it
- OCR and text extraction: reachable. joex processes every upload; no action needed beyond config
- Metadata suggestions from NLP and learned classifiers: reachable. README: suggests correspondents, guesses tags, finds dates using machine learning; runs automatically
- Import from mailboxes: reachable. README: great e-mail integration; scan-mailbox tasks configured through the API-backed settings
- Full-text search across content: reachable. README: fulltext search; admin route to rebuild the index
- Collective insights and statistics: reachable. docs/api/intro: /sec/collective/insights
- Send items by mail or share them: reachable. README screenshot mail-item; share feature documented on docspell.org
- Book-keep amounts or reconcile: not reachable. archive only; custom fields can hold amounts but there is no ledger

## Code stack

- Languages: Scala, Elm
- Frameworks: http4s, doobie, fs2, Stanford CoreNLP, Tailwind
- Package manager: sbt
- Database: PostgreSQL, MariaDB, H2
- Hosting target: Docker Compose (docspell/docker), deb package, zip, Nix / NixOS module, Helm chart

## Evidence and confidence

- formFactor: README: SPA web app over a REST server; docker-compose quick start on port 7880 (confidence 0.95)
- executionModel: Stanford CoreNLP classical NLP, no LLM calls (confidence 0.9)
- operability: README: everything is accessible through a REST/HTTP api; docs/api/intro documents auth, search, admin routes; dsc CLI and Android app are clients (confidence 0.9)
- effort: docspell.org/docs/configure/main: HOCON config, env var mapping, docspell.server and docspell.joex sections; reference.conf in repo (confidence 0.85)
- editions: README: free software under AGPLv3; no paid edition (confidence 0.95)
- active: gh api: pushed 2026-09-02, 2317 stars
- reach:  (confidence 0.85)

## Open questions

- Whether any MCP wrapper exists for Docspell (none surfaced in sourcing)

## Sources

- https://github.com/eikek/docspell (sourcing:support-bookkeeping:curated)
- https://docspell.org/docs/api/ (sourcing:support-bookkeeping:curated)
- https://docspell.org/docs/configure/main/ (analysis)