FAQ

Does my documentation leave my machine?

Not with the default settings. Embeddings are computed locally on your CPU, and the database is inside the same container. The only outbound requests a default installation makes are the one-time model download (which EMBEDDING_OFFLINE=1 removes) and, if you configure them, fetches from your git host or Notion. Switching to OpenAI embeddings does send document text to OpenAI — that is an explicit choice.

Do I need an OpenAI API key?

No. It is optional. See Embedding Models.

Do I need a GPU?

No. Embedding runs on the CPU.

Do I need to install PostgreSQL?

No. It ships inside the container, listening only on the container’s loopback interface.

Which file types are indexed?

Markdown (.md) and MDX (.mdx) by default. A source can also be told to take plain text (.txt), HTML (.html, .htm), CSV (.csv), Word (.docx) and PDF (.pdf) — everything but the first three is converted to Markdown on the way in, so the chunker, the embedder and read_document only ever see one format. An OpenAPI or Swagger specification is its own content type and becomes one document per operation.

There is no OCR, so a scanned PDF, an encrypted one, or a Word file that is all images is refused by name rather than half-indexed, and the rest of the source indexes normally. See Document Sources.

Can one project have several sources?

Yes — that is the point. A local folder, two git repositories, an upload, a Notion workspace and a Confluence site can all feed one endpoint. Each source is mounted under its own name, which becomes the first path segment of its documents. See Document Sources.

Can an agent search across two projects?

No, by design. Projects are isolated end to end. If two bodies of documentation belong to the same question, make them two sources of one project instead.

Can the agent modify my documentation?

No. All three tools are read-only. Contextator never writes to a local directory or pushes to a repository.

Is the MCP endpoint protected?

It can be, one project at a time. A new project is token required by default — creating it mints a first token and shows the secret once, in the creation dialog. The MCP access panel on the project page offers three modes:

• open — anyone who can reach the project’s URL reads everything indexed there. The default before token required became it; still available for a project that should be readable without a credential.
• token required — a client must send Authorization: Bearer ctxm_… or be answered 401. Tokens are minted in the same panel and shown exactly once.
• account required — a client has to act as an account that is a member of the project, checked on every request. It gets that credential through OAuth 2.1, which is what browser-based MCP connectors already speak; a static ctxm_… token names nobody and is refused here.

What a token gives you is access to that endpoint, not an identity: it carries no per-document rules, so whoever holds it reads every document in the project. A credential that does name an account is checked against that account’s membership on every request, in every mode — open included — so signing a connector in as yourself reads a project only if you are a member of it. For a project you leave open to anonymous callers, keeping the port private is still the control. See Security and Connecting AI Clients.

Do I need an account to use the dashboard?

Yes. The dashboard and the admin API are behind a personal account — there is no anonymous mode and no shared password. The first account is created at /setup on a new instance; everyone else gets one from Users in the top-right menu. See Accounts and Permissions.

I lost the setup code

Restart the server. While no account exists a new code is generated and printed on every start, so docker compose restart && docker compose logs -f is the whole recovery. If you would rather not depend on the log, put SETUP_CODE=something-you-remember in .env and restart — a code you chose is used as it is, and never echoed back.

Once the first account exists there is no code any more, and /setup redirects to /login.

I forgot my password

In order of how much you have to reach for:

1. Ask a root or admin colleague. Users page → Reset password hands you a temporary one.
2. Use ADMIN_TOKEN if you have it: POST /api/users/:id/password does the same thing with no account at all, and POST /api/users can create a fresh root one if every account is lost. See Admin API.
3. On an installation run from source, npm run reset-password -- <username> talks to the database directly and prints a new password once. It is not in the Docker image, so on a container install use ADMIN_TOKEN.

Passwords are stored as salted scrypt hashes, so none of these look yours up — they all replace it.

How do I give someone access to one project only?

Create their account with the role member (the default), then open the project, find the Members panel and Add member them as a viewer or an editor. A member sees only the projects it is listed on; every other project answers 404 for it, as if it did not exist.

admin and root accounts reach every project and cannot be added as members — a row saying otherwise would be untrue.

What is the difference between an account and ADMIN_TOKEN?

An account is a person: a username, a password, a role, a session in a browser, and rules that follow from who they are. ADMIN_TOKEN is a single string in .env that grants root permissions on /api/* to anything that sends it — for scripts, CI and cron, which have no person behind them.

It is not the dashboard’s lock any more and does not belong in a browser: it cannot be signed out, cannot be narrowed to one project, and leaves nothing to tell one holder from another. Leave it unset if nothing scripted needs the API.

Does it work in languages other than English?

Yes. The default model covers 100 languages including Turkish. Ask in the language the answer is written in: retrieval covers those languages but does not cross between them, and that is a measured limit of the embedding model rather than a switch.

How often does it re-index?

When you ask it to: the dashboard button, the API, or a push webhook. Indexing is incremental, so frequent runs are cheap. Notion has its own push webhook too, once verified — see Notion — otherwise a scheduled API call is the way there.

Will re-indexing re-embed everything?

No. Files are hashed; unchanged files are skipped. Only Force re-index, or a change of embedding model, rebuilds everything.

How big can a project be?

There is no hard limit. Search stays fast into the tens of thousands of chunks thanks to the HNSW index and the tsvector GIN beside it; the first index run is the expensive part. Separate unrelated knowledge into separate projects for better retrieval, not for capacity.

Can I run several projects at once?

Yes, as many as you like. They share one indexing queue — one project is indexed at a time — but serving searches is concurrent.

What happens if a source fails?

That source reports its own error and the others still index. A source whose content could not be read keeps the documents it had already contributed; a failure never empties a source.

Can I use it with an SSH git remote?

No — HTTPS with an access token only. See Git Repository Source.

Can I change a source’s name?

No. The name is the prefix of every document path it contributes. Delete the source and add it again with the new name (which re-indexes it).

What happens to my files when I delete a project?

Files that Contextator materialised (git checkouts, uploads, Notion pulls) are deleted. Your own documentation is untouched: /docs is mounted read-only and local sources are scanned in place.

Can I put it behind a reverse proxy?

Yes — disable response buffering and set PUBLIC_BASE_URL. See Installation.

Does it support Claude Code, Cursor and Claude Desktop?

Yes, and anything else that speaks MCP. Both MCP transports are served on the same URL, so old and new clients both work without configuration. See Connecting AI Clients.

How do I know the answer came from my documentation?

Every search result carries a file path and a heading breadcrumb, and the server instructs agents to cite the file path they used. read_document returns the file so you can check it.

Why does search say no good match when the answer is in my docs?

The server’s relevance floor is tuned on technical documentation. On encyclopaedic prose it refuses more; a manager can lower the floor for that project, or turn it off there, in the project’s query-log panel, which shows what the new floor would have done to the searches already logged before it is applied. The server’s SEARCH_SCORE_FLOOR=0 turns every project’s floor off. See Embedding Models for what the scores mean.

Where are my uploads stored?

In the contextator-data volume, under the source’s directory. For upload sources that is the only copy — include the volume in your backups. See Backup and Data.

How do I upgrade?

docker compose pull && docker compose up -d. The schema updates itself at startup; there is no migration command. Data lives in volumes and is kept. Building from source instead? See Installation.

What licence is it under?

GNU Affero General Public License, version 3 or later. The full text ships as LICENSE and every running instance serves it at /license.txt; the /license page of your own dashboard summarises it.

It was MIT before 2026-09-18. The AGPL was chosen because Contextator is a server: a plain GPL would let someone fork it, host it as a service and never publish their changes. Section 13 of the AGPL closes that gap.

Can I use it at work? Can I build on it?

Yes to both, and for most people nothing is required in return:

If your organisation forbids AGPL software by policy, or you need to ship it inside something closed, a separate commercial licence can be granted by the copyright holder — ask at tunedness.com.