# Tagvico AI V2 documentation

> Official documentation snapshot intended for language-model context. Follow the section matching the installed major version.

<!-- Source: /docs/v2/index.html.md -->

---
layout: home

hero:
  name: "Tagvico AI v2"
  text: "AI filing for Paperless-ngx, under your control"
  tagline: Self-hosted, reviewable AI metadata for Paperless-ngx with your choice of local or hosted model.
  image:
    src: /tagvico-icon.png
    alt: Tagvico AI
  actions:
    - theme: brand
      text: Install v2
      link: /installation
    - theme: alt
      text: Explore features
      link: /features
    - theme: alt
      text: Choose a provider
      link: /providers

features:
  - icon: 🗂️
    title: Structured filing
    details: Generate titles, tags, correspondents, document types, dates, languages, custom fields, and optional owner assignments.
  - icon: ✅
    title: Review first or automate
    details: Queue suggestions for approval or write validated metadata directly. Change modes without losing queued work.
  - icon: 🔌
    title: Your model, your boundary
    details: Use local Ollama, direct APIs, OpenRouter, Azure, compatible gateways, GitHub Copilot, or experimental ChatGPT subscription access.
  - icon: 📈
    title: Visible operations
    details: Inspect progress, processing history, usage, retries, OCR recovery, rescan actions, and metadata restoration from the web UI.
  - icon: 💬
    title: Optional Telegram access
    details: Give allowlisted family members natural-language search, cited downloads, follow-ups, and uploads through their own Paperless tokens.
---

## Start here

Tagvico AI is a self-hosted companion for an existing Paperless-ngx instance.
It reads OCR text already stored in Paperless, asks your chosen model for a
structured filing suggestion, validates that suggestion, and either queues it
for review or writes it back.

The v2 documentation is frozen under this URL when a future major version is
published. Use the version menu in the navigation to move between major
versions without losing the instructions that match your installation.

::: tip Stable v2
Version 2.0.1 is the current stable v2 release. Pin the immutable image version,
back up the data volume before upgrades, and start new installations in
**Review first** mode.
:::

---

<!-- Source: /docs/v2/installation.md -->

# Install Tagvico AI v2

You need Docker Compose, a running Paperless-ngx installation, its base URL,
and a Paperless API token. Tagvico runs as one container and stores its local
configuration, admin account, history, and queues in a persistent volume.

## 1. Create the Compose file

Create a new directory and save this as `docker-compose.yml`:

```yaml
services:
  tagvico-ai:
    image: ghcr.io/arturict/tagvico-ai:2.0.1
    container_name: tagvico-ai
    restart: unless-stopped
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges=true
    ports:
      - "8080:3000"
    environment:
      TAGVICO_AI_PORT: "3000"
    volumes:
      - tagvico_ai_data:/app/data

volumes:
  tagvico_ai_data:
```

Pin the exact v2 release you intend to run. Do not use `latest` for a
production install because it makes upgrades and rollback ambiguous.

## 2. Start and check the container

```bash
docker compose up -d
docker compose ps
curl http://localhost:8080/health
```

Open `http://localhost:8080/setup` after the health check succeeds.

If the setup browser is on a different machine, temporarily add
`ALLOW_REMOTE_SETUP: "yes"` to the service environment, recreate the
container, and remove it immediately after the first setup completes. Do not
leave it enabled for normal operation.

![Tagvico AI v2 sign-in screen captured from a clean VM 113 browser session](/screenshots/sign-in.png)

This sanitized capture shows the local admin sign-in presented after setup. It
contains no credentials, private hostnames, document data, or account details.

## 3. Finish guided setup

1. Create the local Tagvico admin account.
2. Enter the Paperless base URL without `/api`, then paste a Paperless API token
   and test the connection.
3. Choose a [model provider](./providers) and test its credentials or endpoint.
4. Select **Review first** for approval-based filing or **Automatic** for direct
   writes, then choose which metadata fields Tagvico may change.

After saving the provider, inspect the detailed application health response.
Unlike `/health`, this endpoint reports the configured model adapter's health
when that adapter exposes a health check:

```bash
curl --fail http://localhost:8080/api/health
```

Some compatible and subscription-backed adapters report their health as
unknown rather than making a billable test request. Use the **Test connection**
actions in Settings to verify both Paperless and the selected model provider
before processing documents.

If Paperless runs on the Docker host, use `host.docker.internal` on Docker
Desktop or the host's LAN address on Linux. If both containers share a Docker
network, use the Paperless Compose service name.

::: tip Safer first run
Use **Review first**, enable only a small controlled tag vocabulary, and test
with synthetic or non-sensitive documents before allowing automatic writes.
:::

## Optional Telegram bot

Create a bot with BotFather, obtain each person's Telegram numeric user ID, and
create a separate Paperless API token for each person. Add the following
environment values to the Tagvico service:

```yaml
environment:
  TELEGRAM_BOT_ENABLED: "yes"
  TELEGRAM_BOT_TOKEN: "123456:replace-with-the-bot-token"
  TELEGRAM_USERS_JSON: >-
    [{"telegramId":"123456789","paperlessToken":"one-users-paperless-token"}]
  # Optional: bypasses the Tagvico review queue for metadata on bot uploads.
  TELEGRAM_UPLOAD_AUTOMATIC_METADATA: "no"
```

The remaining optional tuning variables are
`TELEGRAM_POLL_TIMEOUT_SECONDS` (default `30`),
`TELEGRAM_UPLOAD_TIMEOUT_SECONDS` (default `180`),
`TELEGRAM_MAX_DOCUMENTS` (default `8`), `TELEGRAM_HISTORY_TURNS`
(default `6`), and `TELEGRAM_MAX_FILE_BYTES` (default `20971520`). The bundled
Compose file passes every Telegram setting through to the application container.

`paperlessUrl` may be added to an individual allowlist entry; otherwise the
normal `PAPERLESS_API_URL` is used. Restart Tagvico after changing this process
configuration. The standard Telegram Bot API can download uploads up to 20 MB,
and Tagvico enforces that limit. Unknown IDs and non-private chats receive no
response.

Read [Privacy and security](./privacy) before enabling the bot. Telegram bot
chats are not end-to-end encrypted, and model-provider data terms still apply.

## Docker run alternative

```bash
docker volume create tagvico_ai_data
docker run -d \
  --name tagvico-ai \
  --restart unless-stopped \
  --cap-drop ALL \
  --security-opt no-new-privileges=true \
  -p 8080:3000 \
  -e TAGVICO_AI_PORT=3000 \
  -v tagvico_ai_data:/app/data \
  ghcr.io/arturict/tagvico-ai:2.0.1
```

Setup is a one-time bootstrap; later configuration changes require signing in.
For a remote browser, add `-e ALLOW_REMOTE_SETUP=yes` only until setup is
finished, then recreate the container without it.

## Next steps

- Compare the [supported providers](./providers) and understand where document
  text is processed.
- Review the [privacy and security boundaries](./privacy) before using real
  documents.
- Keep the [troubleshooting guide](./troubleshooting) available while validating
  the first processing run.

---

<!-- Source: /docs/v2/upgrading.md -->

# Upgrade to or within v2

The `tagvico_ai_data` volume is the upgrade boundary. It holds settings,
processing history, queues, and the local admin account. Keep it, back it up,
and change only the container image during a normal upgrade.

## Before upgrading

1. Read the [release notes](https://github.com/arturict/tagvico-ai/releases) and
   note any v2 migration warnings.
2. Keep **Review first** enabled if the release changes metadata behavior.
3. Stop Tagvico and back up its named volume:

```bash
docker compose stop tagvico-ai
docker run --rm \
  -v tagvico_ai_data:/source:ro \
  -v "$PWD":/backup \
  alpine tar czf /backup/tagvico-ai-data.tgz -C /source .
```

## Pull the pinned release

Update `image:` in `docker-compose.yml` to the exact release tag, then run:

```bash
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 tagvico-ai
curl http://localhost:8080/health
```

After signing in, confirm the displayed version, test the Paperless connection,
and check `/api/health`. Process one non-sensitive document in **Review first**
before re-enabling Automatic mode.

Tagvico checkpoints SQLite and creates a pre-migration database backup before
schema upgrades. The external volume backup remains the safest rollback point.

## Roll back

Use this only with the external backup made above. Do not run two Tagvico
versions against the same volume at the same time.

```bash
docker compose down
docker volume rm tagvico_ai_data
docker volume create tagvico_ai_data
docker run --rm \
  -v tagvico_ai_data:/target \
  -v "$PWD":/backup:ro \
  alpine sh -c 'tar xzf /backup/tagvico-ai-data.tgz -C /target'
# Change image: back to the previous immutable release tag, then:
docker compose up -d
docker compose logs --tail=100 tagvico-ai
```

Confirm that `/health`, sign-in, configuration, and one representative
**Review first** suggestion work before returning to normal operation.

::: danger v1 to v2
Treat a major-version upgrade as a maintenance window. Back up the volume,
read the v2 release notes, migrate deprecated environment-variable aliases to
their `TAGVICO_*` replacements, and verify suggestions in **Review first**
before returning to automatic writes.
:::

---

<!-- Source: /docs/v2/removing.md -->

# Remove Tagvico AI

Removing the container does not remove Paperless documents or metadata already
written to them. It also leaves the named data volume intact unless you
explicitly delete it.

## Keep data for a later reinstall

```bash
docker compose down
```

You can reinstall the same or a compatible v2 image later and attach the
existing `tagvico_ai_data` volume.

## Permanently delete local Tagvico data

First create a final backup if you may need settings, history, queues, or the
local admin account. Then remove the Compose stack and its named volume:

```bash
docker compose down --volumes
```

If you created the container with `docker run`:

```bash
docker rm -f tagvico-ai
docker volume rm tagvico_ai_data
```

::: danger This cannot be undone
Deleting `tagvico_ai_data` permanently removes Tagvico's local configuration,
credentials, history, review queue, snapshots, and admin account. It does not
revert metadata already written to Paperless-ngx. Use History restoration
before removal if you want to revert supported metadata snapshots.
:::

Finally, remove any Tagvico-specific API token from Paperless and revoke hosted
provider credentials that were dedicated to this installation.

---

<!-- Source: /docs/v2/features.md -->

# Feature showcase

## Operations at a glance

The dashboard shows processing progress, runner state, Paperless vocabulary
counts, recent activity, and token/cost-efficiency signals. **Scan now** starts
an on-demand pass without waiting for the schedule.

## Controlled tagging

Choose whether the model may create open-ended tags or must stay within a
controlled vocabulary. Tag groups make a larger Paperless tag catalog easier
to manage, and a per-document maximum prevents noisy assignments.

![Controlled tagging groups with generic finance, legal, home, insurance, health, and work tags](/screenshots/controlled-tagging.png)

Generic category tags are shown in this capture. No document contents, names,
credentials, account identifiers, or private endpoints are visible.

## Review-first filing

In **Review first** mode, durable suggestions wait for approval. Inspect the
metadata diff, apply it, reject it, or leave it queued. Switching to Automatic
mode does not discard already queued suggestions.

In **Automatic** mode, Tagvico validates and writes enabled fields directly to
Paperless. Both modes support titles, tags, correspondents, document types,
dates, languages, custom fields, and optional owner assignment.

## History, restoration, and retry control

Every processing run records status and usage. History supports manual reruns,
rescan, and restoration from the first metadata snapshot captured before
Tagvico changed a document. Provider failures are retried, then moved to a
terminal state instead of looping forever.

## OCR rescue

Documents with insufficient OCR can enter a durable rescue queue. Configure
Mistral OCR, an OpenAI-compatible vision endpoint, or Ollama vision. Local PDF
OCR limits rendered pages with `OCR_MAX_PAGES`; interrupted work returns to the
pending queue after restart.

## Subscription-backed model discovery

The experimental ChatGPT provider uses the official Codex runtime and shows
the live model catalog returned for the signed-in account, including GPT-5.6
Luna when that account exposes it. GitHub Copilot uses
the official Copilot SDK and likewise limits choices to account-visible models.
Agent tools are denied for these document-extraction paths.

## Optional Telegram family interface

An opt-in long-polling bot lets allowlisted people search the archive in natural
language, ask follow-up questions, download cited originals, and send a PDF or
photo into Paperless. Each Telegram ID maps to its own Paperless API token;
unknown users and group chats are ignored, and Paperless enforces every search,
download, upload, and metadata permission.

Conversation history is bounded and held in memory only. `/clear` removes one
person's history, and a restart removes all histories. Uploads wait for the
Paperless consumption task, link the existing document when Paperless reports a
duplicate, and can optionally run Tagvico metadata classification. Automatic
metadata for bot uploads is a separate explicit opt-in because it bypasses the
web review queue.

![Sanitized ChatGPT subscription model selector in Tagvico settings](/screenshots/chatgpt-models.png)

## Optional anonymous installation analytics

Installation analytics are off by default. Administrators can preview the
complete outbound heartbeat in Settings before opting in. Rotating daily and
monthly identifiers support active-installation counts without creating a
permanent installation profile; document content, metadata, URLs, identities,
keys, exact counts, and errors are never included. See [Privacy and
security](./privacy) for the complete field list and retention design.

---

<!-- Source: /docs/v2/paperless-ai-tagging.md -->

# AI tagging and metadata for Paperless-ngx

Tagvico AI is a self-hosted companion for people who want more control over
automatic Paperless-ngx metadata. It reads OCR text through the Paperless API,
asks a local or hosted model for structured fields, validates the result, and
either queues a reviewable diff or writes approved fields back.

## When Tagvico is useful

- You want local AI tagging with Ollama, LM Studio, vLLM, or another compatible
  endpoint.
- You need titles, dates, correspondents, document types, languages, custom
  fields, or owner assignment in addition to tags.
- You want generated values constrained to an existing vocabulary.
- You want to inspect suggestions before changing Paperless documents.
- You need history, retry queues, metadata restoration, and visible token/cost
  signals around the classification workflow.

Paperless-ngx's own matching remains the simpler choice when deterministic
rules or its built-in learning already classify an archive reliably. Tagvico
adds value when documents vary, several fields must be extracted together, or
the operator wants to choose and evaluate a modern language model.

## Local and hosted privacy boundaries

With Ollama or another endpoint on your network, OCR text can remain on
infrastructure you control. Selecting OpenAI, Anthropic, OpenRouter, Azure, or
another hosted service sends the document content required for classification
to that provider. Tagvico does not proxy document content through a
Tagvico-operated cloud.

Optional installation analytics are off by default and never contain document
content or metadata. See [Privacy and security](./privacy).

## A safe evaluation workflow

1. Install with an immutable image tag and back up the data volume.
2. Start in **Review first** with synthetic or non-sensitive documents.
3. Enable a small controlled tag vocabulary.
4. Test 20–50 representative documents and record correctness per field.
5. Move only reliable fields or document types to Automatic mode.

Use the same test set when comparing providers. Count missing and incorrect
fields rather than judging the model's prose. The [provider guide](./providers)
contains cost-conscious starting points.

---

<!-- Source: /docs/v2/providers.md -->

# Model provider overview

Provider choice determines where OCR text is processed, how credentials are
managed, which models are visible, and which cost modes are available. Validate
quality with representative documents before enabling Automatic writes. See
[Privacy and security](./privacy) before sending real document text to a hosted
service.

| Provider | Best for | Authentication / endpoint | Notes |
| --- | --- | --- | --- |
| OpenRouter | Curated cloud choice and easy model switching | API key | Recommended hosted starting point; requests are forwarded to the selected upstream provider. |
| Ollama | Fully local inference | Local `/api/chat` endpoint | Keeps processing on infrastructure you control; model quality and speed depend on hardware. |
| Ollama Cloud | Hosted Ollama models | API key | No local GPU required; document text leaves your network. |
| OpenAI direct | Native OpenAI models, Flex, and Batch | API key | Flex and Batch are available only for supported models. |
| Anthropic direct | Claude and Message Batches | API key | Supports standard requests and discounted asynchronous batches. |
| OpenCode Go | Subscription inference gateway | Go API key | OpenAI-compatible request path with provider-controlled limits. |
| GitHub Copilot | Account-scoped model discovery | OAuth device login or supported token | Uses the official SDK; every agent tool is denied. |
| OpenAI-compatible | LM Studio, LiteLLM, vLLM, custom gateways | Base URL and optional key | Use an endpoint that implements OpenAI Chat Completions. |
| Azure OpenAI | Existing Azure deployments and governance | Endpoint, deployment, API key | Model availability follows your Azure deployment. |
| ChatGPT subscription | Experimental private, low-volume use | Codex device login | Uses the official Codex runtime and the account's live catalog, which may include GPT-5.6 Luna; this is not an API SLA. |

## Cost-conscious recommendations

These are starting points for document classification, where consistent
structured output matters more than maximum general-purpose reasoning. Test at
least 20–50 representative documents in **Review first** before deciding that a
model is good enough for Automatic mode.

| Provider | Recommended starting point | Why it is a good-value choice |
| --- | --- | --- |
| OpenRouter | **GPT-5.4 Mini** with low reasoning | Best general hosted default in Tagvico: reliable structured extraction without paying for a frontier-sized model. Try **GPT-5.4 Nano** or **Gemini 3.1 Flash Lite** for very clean, repetitive documents; avoid the free router for unattended production because the underlying model can change. |
| Ollama | **Qwen 3.5 4B** on modest hardware; **Qwen 3.5 9B** when it fits comfortably | Qwen 3.5 is the current value-oriented starting family for structured, multilingual filing. The 4B download is about 3.4 GB; the 9B build is about 6.6 GB and is the better quality target when memory allows. **Gemma 3 4B** is a strong compact alternative. Gemma 4 is newer, but even its E2B/E4B edge variants have larger model files and are less attractive for a cheapest-first setup. |
| Ollama Cloud | **gpt-oss:20b-cloud** | Tagvico's default balances capability with a moderate hosted footprint and avoids buying or running a GPU. Recheck the cloud catalog and account limits before committing to it. |
| OpenAI direct | **GPT-5.4 Mini**; use **Batch** for non-urgent archives | Mini is the balanced default. **GPT-5.4 Nano** can reduce cost further for predictable invoices and statements. Batch is preferable when turnaround can wait; Flex is useful when supported and occasional slower availability is acceptable. |
| Anthropic direct | **Claude Haiku 4.5**; use Message Batches when latency is unimportant | Haiku is the speed-and-cost tier and is normally sufficient for titles, tags, and other structured fields. Move to a larger Claude model only for difficult layouts or extraction failures. |
| OpenCode Go | **DeepSeek V4 Flash** | This is Tagvico's budget-oriented default for the Go gateway. It suits classification-heavy workloads; confirm the current subscription allowance and gateway model catalog. |
| GitHub Copilot | **GPT-5.4 Mini** when the signed-in plan exposes it | It offers a strong quality/cost balance without a separate per-token key inside Tagvico. Prefer a model with the lowest billing multiplier that still passes your test set, because plan entitlements differ. |
| OpenAI-compatible | A **mini**, **flash**, or roughly **8B–20B instruct** model supported by your gateway | Compatible endpoints vary too much for one universal slug. Start small, require reliable JSON/structured output, and increase model size only when the error rate justifies the extra compute or gateway cost. |
| Azure OpenAI | A deployment of **GPT-5.4 Mini** | Mini is the normal value choice when Azure governance is required. Azure deployment availability and regional pricing take precedence over the public model name. |
| ChatGPT subscription | **GPT-5.6 Luna** when it appears in the account catalog | Luna is the preferred low-cost GPT-5.6 tier for repetitive filing. Use **GPT-5.4 Mini** as the fallback. Subscription access is experimental, intended for one trusted low-volume installation, and is not an API service guarantee. |

::: tip A practical selection rule
Start with the recommended mini, flash, Haiku, or Luna tier and low reasoning.
Measure incorrect or missing fields—not how impressive the prose sounds. Move
up one tier only when the cheaper model fails the same field or document type
repeatedly.
:::

### Ollama sizing notes

The official [Qwen 3.5 library](https://ollama.com/library/qwen3.5) currently
offers `0.8b`, `2b`, `4b`, `9b`, and larger variants—there is no official 7B
or 8B tag. For Tagvico, start with:

- `qwen3.5:4b` for a low-memory trial and routine, clean documents.
- `qwen3.5:9b` for the preferred local balance when the roughly 6.6 GB model
  file plus runtime overhead fits comfortably.
- [`gemma3:4b`](https://ollama.com/library/gemma3) for a compact multilingual
  alternative with a roughly 3.3 GB model file.
- [`gemma4:e2b` or `gemma4:e4b`](https://ollama.com/library/gemma4) only when
  you specifically want Gemma 4 and can
  accommodate their roughly 7.2 GB or 9.6 GB model files. Their “E” sizes mean
  effective parameters, not download or runtime memory.

Actual RAM or VRAM use is higher than the model file and rises with context
length. Keep the context window only as large as your documents require, then
compare field accuracy and throughput on the same test set.

## Switching providers

Use **Settings → AI provider**, complete the selected provider form, and test
the connection. With environment configuration, change `AI_PROVIDER`, keep the
provider-specific values in `data/.env`, and restart the container. Each
adapter has its own configuration namespace, so switching does not require
deleting the previous provider's values.

## Processing modes

- **Standard** processes each document immediately.
- **OpenAI Flex** reduces cost for supported OpenAI models in exchange for
  slower or less predictable availability.
- **Batch** submits asynchronous discounted work to OpenAI or Anthropic and may
  take up to 24 hours.

::: warning Catalogs change
Model names, pricing, quotas, subscription entitlements, and regional
availability are provider-controlled. Recheck the provider catalog before each
Tagvico release; it is not part of the compatibility contract.
:::

For current model identifiers and account entitlements, use the catalog shown
inside Tagvico after authentication. The documentation intentionally does not
hard-code model names that providers may rename or withdraw.

---

<!-- Source: /docs/v2/privacy.md -->

# Privacy and security

Tagvico reads OCR text and metadata from Paperless-ngx. A local Ollama or
compatible endpoint can keep that processing on infrastructure you control.
When you select a hosted provider, the document content required for
classification is sent to that provider under its terms.

## Deployment boundaries

- Provider secrets are stored in `data/.env` and are not written to the
  processing database.
- The container drops Linux capabilities and enables `no-new-privileges` in the
  recommended Compose configuration.
- Use a dedicated Paperless API token and only expose the Tagvico web port to
  trusted networks.
- Start with Review first and a controlled tag vocabulary.
- Back up the data volume before schema upgrades.

## Telegram bot boundary

The optional Telegram interface is not a local transport and Telegram bot chats
are not end-to-end encrypted. Questions, photos, PDFs, and any original sent
back through a download button pass through Telegram under its terms. Retrieved
Paperless OCR and the user's question are sent to the configured Tagvico model
provider. Choosing local Ollama or a local compatible endpoint keeps the model
step on infrastructure you control, but does not change the Telegram boundary.

Only explicitly allowlisted Telegram IDs are processed, only private chats are
accepted, and each ID has a separate Paperless API token. Paperless therefore
remains responsible for document visibility and mutation permissions. The
allowlist and tokens are configuration secrets; do not commit them. The bot has
no conversation database: bounded per-user history lives in process memory and
is removed by `/clear` or restart.

Answers derived from OCR can be incomplete or wrong. In particular, totals and
comparisons are assistant summaries rather than accounting-grade calculations;
use the cited-original buttons to verify them.

## Screenshot policy

Documentation screenshots must be inspected as final rendered pixels before
commit. They must not show API keys, tokens, real document text, personal names,
email addresses, account identifiers, private hostnames, or internal URLs.
Empty states, synthetic metadata, generic tags, and non-identifying aggregate
counts are acceptable.

The screenshots in this v2 guide use generic tag labels and sanitized document
state. They demonstrate product behavior without exposing source documents or
credentials.

## Optional installation analytics

Tagvico's anonymous installation analytics are disabled by default. You can
explicitly opt in from **Settings → Privacy → Anonymous installation
analytics**, preview the exact payload before sharing, send a test heartbeat,
or disable sharing again at any time.

When enabled, Tagvico sends one coarse heartbeat roughly every 24 hours. It
contains the application version, a broad processed-count
bucket, write mode, a broad provider category, three feature booleans, and
rotating daily/monthly identifiers. The locally generated secret used to derive
those identifiers never leaves the installation, and the monthly identifier
changes every month.

Tagvico never includes document text or metadata, names, emails, user or
document IDs, Paperless URLs, API keys, exact document counts, exact model
names, errors, hostnames, or IP-derived location in the payload. Receiver rows
expire after 62 days and only aggregate opted-in installation counts should be
published.

Set `TAGVICO_TELEMETRY_ENABLED=no` to enforce the default from the environment.
Self-hosted distributors may override `TAGVICO_TELEMETRY_ENDPOINT`; it must use
HTTPS. The complete policy and receiver source are available in
[`PRIVACY_POLICY.md`](https://github.com/arturict/tagvico-ai/blob/main/PRIVACY_POLICY.md)
and [`telemetry/`](https://github.com/arturict/tagvico-ai/tree/main/telemetry).

---

<!-- Source: /docs/v2/troubleshooting.md -->

# Troubleshooting

Start with the container status, recent logs, and both health endpoints:

```bash
docker compose ps
docker compose logs --tail=200 tagvico-ai
curl --fail http://localhost:8080/health
curl --fail http://localhost:8080/api/health
```

`/health` verifies the Tagvico process and its database. `/api/health` also
reports the configured model adapter's health when the adapter exposes a
health check, and returns `503` on an explicit failure. An `unknown` provider
result is not a successful connection test; use the **Test connection** actions
in Settings to verify Paperless and the selected provider.

## Setup returns 403

Remote setup is disabled by default. When the browser is not running on the
same machine as Tagvico, temporarily set `ALLOW_REMOTE_SETUP=yes`, recreate the
container, and complete setup. Remove the setting afterward and recreate the
container again.

## Setup returns 409

The instance already has setup data. This is intentional: public setup cannot
replace an existing admin account or its connection settings. Sign in and use
Settings for normal changes. For disaster recovery, restore a known-good data
volume backup rather than exposing a reset endpoint.

## Paperless connection fails

- Use the Paperless base URL without `/api`.
- Verify the API token in Paperless and use a dedicated token where possible.
- From a container, `localhost` refers to that container—not the Docker host.
  Use a shared Compose network and the Paperless service name, or a reachable
  host address.
- Test the exact URL from the Docker host before changing Tagvico settings.

## Provider health is degraded

Open **Settings → AI provider**, confirm the selected provider, and run its
connection test. Check the endpoint, model, credentials, account entitlement,
and provider status. Model catalogs and quotas are controlled by the provider
and may change independently of Tagvico.

For a local Ollama endpoint, confirm the model is pulled and that Ollama listens
on an address reachable from the Tagvico container. An endpoint bound only to
the host loopback interface is not normally reachable from another container.

## Documents are not processing

1. Check **Operations** for runner state, retries, terminal failures, or OCR
   rescue work.
2. Confirm the Paperless token can see the expected documents.
3. Use **Scan now** for an immediate pass.
4. Inspect **History** for the specific failure instead of repeatedly rescanning.

Keep **Review first** enabled while diagnosing write behavior. A suggestion that
is already queued remains reviewable when the processing mode changes.

## Upgrade does not start cleanly

Do not run two Tagvico versions against the same data volume. Stop the stack,
preserve the failed container logs, and follow the [rollback procedure](./upgrading#roll-back).
Restore the pre-upgrade volume backup when the new release migrated the database
and the previous image cannot read it.

## Get more help

When reporting a problem, include the Tagvico version, deployment method,
provider name, relevant sanitized log lines, and the failing health status.
Remove API keys, tokens, document text, personal data, account identifiers, and
private URLs before posting an issue in the
[GitHub issue tracker](https://github.com/arturict/tagvico-ai/issues).

---