suchi

README

suchi

A self-hosted document archive that files itself.
_{Sanskrit सूची — "an index, a catalog, a list"; pronounced SOO-chee, like kimchi.}

Live demo · Quick start · Docs · Why I built it

Drop in a scan, an email attachment or a photo. Suchi reads it, gives it a useful title and files what it is sure about into a numbered category tree. Anything it is unsure about waits in the Inbox for you instead of being guessed. Originals are never modified, and the archive is also rendered as a plain folder tree you can browse without the app.

Suchi began as a personal and household archive. The same principles apply more broadly, so the built-in filing trees also include approachable starting points for freelancers and smaller teams.

• One binary. Go, SQLite and files on disk. No Postgres, Redis, queue or telemetry service. Nothing calls out until you enable an integration.
• One filing model. Numbered categories in the Johnny.Decimal style instead of overlapping tags, types and storage paths. Start from a built-in tree or import your own.
• Deterministic automations first. Suchi calls its explicit text-matching rules automations; they run before any model. An optional model, either local (Ollama, llama.cpp) or any OpenAI-compatible endpoint, suggests titles, categories and dates. Sending document text to a hosted model requires explicit acknowledgement.
• Capture from anywhere. Browser upload, watched folders, your own IMAP mailbox, and the Suchi Companion app for iOS and Android, which can queue and keep scans while offline.
• Find it and follow up. OCR and full-text search, a calendar of dates linked to the text they came from, and document questions answered with links to the documents used.

[!NOTE] Suchi is early (v0.4.1). Back up the data directory, test a restore before relying on it, and read the database compatibility policy before upgrading.

Capabilities

Suchi combines SQLite, content-addressed storage, a Svelte interface, and a scoped HTTP API in one static Go binary. Original and derived bytes are stored immutably by SHA-256; SQLite metadata and the API—not the content store—enforce access.

• OCR, thumbnails, barcodes, encrypted PDFs, ZUGFeRD invoices, and common image, ebook, Office, OpenDocument, mail, archive, and text formats.
• Full-text search, numbered filing, physical archive serial numbers, retained QR-label scan splitting, version notes, typed custom fields, named exact-document links, saved Views, and folder layouts.
• Filing systems with permanent codes, direct membership plus document ACLs, and SYS.AC category addresses after introduction; a single archive shows category codes. Numeric document IDs remain separate.
• Browser, watched-folder, IMAP, and mobile intake; takeout exports, supported third-party imports, document versions, backups, and restore tooling.
• Automations, approvals, selective rescans, optional model classification, Ask your documents, and suggested dates. Model use is optional and hosted egress requires acknowledgement.
• Groups, object ACLs, OIDC, local authenticator/recovery-code 2FA, scoped tokens, Network-only and Public share links, audit events, MCP, and the Android/iOS Suchi Companion.

Reproducible binary-size and startup measurements live under hack/bench/latest-published/. See the comparison and architecture for scope and tradeoffs.

Container images · Releases · Actions

Quick Start

The versioned standard image is a convenient local evaluation starting point:

docker volume create suchi-data
docker run -d --name suchi --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -e PUBLIC_URL=http://127.0.0.1:8000 \
  -v suchi-data:/data \
  ghcr.io/johnnybravo-xyz/suchi:v0.4.1
docker logs suchi 2>&1 | grep token_minted

Open http://127.0.0.1:8000, enter the one-time setup token, and create the first admin account. The token expires after 24 hours; attempting to use an expired token writes a replacement to the server log. A minimal compose.yaml is also provided for operators who want editable mounts, networks, and image pins. See Getting started for direct binary, reverse-proxy, NAS, and production deployment paths.

After creating the administrator, choose a filing tree in Settings > Archive configuration > Filing tree. This is the only required archive setup step; the reminder remains until a preset, imported tree, or explicit Blank choice is saved.

This quick start is bound to loopback and pins the v0.4.1 image. A production server, including one reached by the mobile app, must use HTTPS and pin the selected release by its published image digest.

Images

• v0.4.1 / latest: Alpine. Supports all listed formats and indexes scanned PDFs with Tesseract.
• v0.4.1-full / latest-full: Debian. Adds OCRmyPDF so downloaded scanned PDFs can retain a searchable text layer.

Both images include anydoc, DjVu, HEIC/HEIF, and Outlook MSG support. The full image changes only the scanned-PDF archive behavior. See Supported file types for the exact routing and bare-metal dependencies.

Development

The workspace requires Go 1.27.3 or newer; plugin-api remains compatible with Go 1.24. SPA and documentation development require Bun.

git clone https://github.com/johnnybravo-xyz/suchi.git
cd suchi
make install-hooks
make check
make run

make run uses /tmp/suchi-dev and listens on http://127.0.0.1:8000. Useful verification commands:

make test
make lint
make ui-check
make smoke
make smoke-ingest
./hack/smoke-anydoc-docx.sh
make smoke-mail

The ci workflow runs formatting, vet, tests, static analysis, and the SPA build. The smoke workflow boots both images and verifies real PDF OCR and Outlook MSG ingestion.

Repository

plugin-api/   shared extension interfaces and types
core/         API, database, ingest pipeline, jobs, auth, and embedded UI
plugins/      local auth, OIDC, and LLM classifier modules
distro/       importable app assembly and shipped suchi / suchi-mcp entry points
ui/           Svelte SPA source
deploy/       self-hosting templates and mail intake sidecar
docs/         published documentation source
hack/         fixtures, benchmarks, smoke tests, and developer tools

The root module contains the shipped application; plugin-api stays separate for external plugins and the utilities under hack/ keep isolated dependency graphs. The empty ui module keeps Go tooling out of frontend dependencies. make build uses Bun to install locked frontend dependencies, generates the ignored SPA bundle, and produces dist/suchi; suchi doctor inventories configured egress, pipeline tools, schema and taxonomy state, data-directory writability, and selected job, backup, audit, upload-limit, and CAS indicators.

Documentation

• Documentation
• Configuration
• CLI reference
• HTTP API
• Filing systems and taxonomy imports
• Supported file types
• Deployment templates
• Backup and restore
• Contributing
• Security policy

Works with Johnny.Decimal, a trademark of Coruscade Pty Ltd. Suchi is independent and not endorsed by them. The built-in filing trees are CC0-1.0, unreviewed and not compliance advice. Filing systems share one server, SQLite/FTS and CAS; server administrators and host/backup operators remain trusted. A code prefix is not separate infrastructure or a legal-independence guarantee. See Permissions for the application boundary.

License

Copyright (c) 2026 Ritesh Shrivastav. Suchi is available under two licenses:

• GNU Affero General Public License v3.0 — free for everyone. Note that if you modify Suchi and let others interact with it over a network, AGPL section 13 requires you to offer them its complete corresponding source.
• Commercial license — for embedding Suchi in a proprietary product, or for running a modified instance as a service without that source-offer obligation. Write to contact@suchi.page.

Every feature, including OIDC, access controls, approvals and MCP, is in the AGPL version; no paid tier holds features back. The CLA exists so contributions can also be offered under the commercial license.

The AGPL offer begins with Suchi's first public release. Before that release, its repository and container images were private development artifacts and were not distributed to any third party.

The plugin interfaces in plugin-api/ are a separate module licensed under the Apache License 2.0, so third-party plugins may be released under any license, including proprietary ones.

Third-party components and their terms are listed in NOTICE. Contributions are accepted under the Contributor License Agreement.