Technical FAQ | RepliSec

Architecture

One container. One data directory.

What is RepliSec, architecturally?

A single container that runs two processes and stores everything in one directory.

Next.js (App Router) serves the UI on port 3000 and proxies /api/* to the backend.
FastAPI runs the backend on 127.0.0.1:8000, bound to loopback, so it is not reachable from outside the container.
SQLite holds questionnaires, answers, the knowledge base and the approved answer library.
Chroma (embedded mode, not a server) holds the vectors used for semantic search.
SQLite FTS5 holds the full-text index used for lexical search.

All state lives under /app/data: replisec.db, chroma/, and documents/ for the files you uploaded. Mount that one directory and you have backed up everything. Delete it and you are back to a clean install.

The container runs as a non-root user with tini as PID 1.

Where does my data go?

Nowhere, unless you configure a cloud model and use a mode that permits it. Concretely:

Your documents and answers are written to disk in the directory you mounted. They are never uploaded anywhere by RepliSec.
Embeddings are always computed locally. RepliSec uses sentence-transformers with the all-MiniLM-L6-v2 model (384 dimensions) running in-process. There is no configuration in which your text is sent to a third party to be embedded.
The only outbound call RepliSec makes is to the LLM you configured, and only in a mode that permits LLM use. If you point it at Ollama on your own machine, that call does not leave your machine either.
No telemetry. Chroma, Next.js and LiteLLM all ship usage telemetry enabled by default; all three are disabled in the image.

How do I back it up?

Copy /app/data. That is the whole application state: database, vectors and uploaded files. Stop the container first for a consistent snapshot, or take the copy while it is running and accept that an in-flight upload may be missing.

To start over, delete the directory and restart.

Compliance modes

Enforced in the import graph, not the settings page.

What are compliance modes, and why do they exist?

Some organisations are contractually prohibited from using AI on customer material. Most tools answer that with a setting. RepliSec answers it with the import graph.

What each compliance mode permits
Mode	LLM	Embeddings	What it means
Standard	Yes	Yes	AI drafts answers from your knowledge base.
Disclosure	Yes	Yes	Same, and exports carry an AI disclosure report.
Human Authored	Reference only	Yes	Retrieval is allowed; the answer field blocks paste, so a person types the response.
Library Only (Semantic)	No	Yes	Answers come only from your approved library, matched by meaning.
Library Only (Lexical)	No	No	Keyword matching only. No neural models are loaded at all.

The last row is the load-bearing one. When RepliSec boots with REPLISEC_COMPLIANCE_MODE_DEFAULT=library_only_lexical, the modules that would import sentence-transformers and litellm are short-circuited at import time. Those libraries never enter the process. It is not that the code declines to call them. The code that could call them is not there.

Every other mode enforces the same rules per call: each entry point that could reach a model asks the gate first.

Can I run it completely offline?

Yes, with one thing to know about the first run.

library_only_lexical is offline by construction. It loads no neural models, so there is nothing to download:

docker run --network none --rm -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e REPLISEC_ENCRYPTION_KEY=$(openssl rand -base64 32) \
  -e REPLISEC_COMPLIANCE_MODE_DEFAULT=library_only_lexical \
  replisec:latest

The semantic modes need the embedding model on disk first. all-MiniLM-L6-v2 is about 90 MB and is downloaded from Hugging Face the first time it is used. It is not baked into the image. So the sequence for an air-gapped semantic deployment is: run once with network access to warm the cache, then run with --network none afterwards.

Local models

A fully local pipeline, if you want one.

How do I use it with a local LLM?

RepliSec talks to models through LiteLLM, so anything LiteLLM can reach, it can use. For a fully local setup, Ollama is the shortest path.

Install and start Ollama on your host (not in the container):

brew install ollama          # macOS; see ollama.com for Linux/Windows
ollama serve

Pull a model. An 8B model is a reasonable starting point on a laptop:
```
ollama pull llama3.1:8b
```

Start RepliSec. Nothing special is needed, and no API key:

docker run -d --rm --name replisec \
  -p 3000:3000 -v $(pwd)/data:/app/data \
  -e REPLISEC_ENCRYPTION_KEY=$(openssl rand -base64 32) \
  replisec:latest

Point RepliSec at Ollama. Open http://localhost:3000, go to Settings → AI Provider, and choose Ollama (local). Two fields:
- Ollama URL: http://host.docker.internal:11434 on macOS and Windows. On Linux, use http://172.17.0.1:11434, or run the container with --network host and use http://localhost:11434.
- Model: llama3.1:8b, or whatever you pulled; the name must match ollama list exactly.
There is no API key field, because there is no API key.
Test it. Settings has a Test connection button. Then upload a document and generate answers on a questionnaire. The whole pipeline is now local: local embeddings, local vector store, local model.

Other local runtimes. LM Studio, vLLM, LocalAI and anything else exposing an OpenAI-shaped API work through the OpenAI-compatible provider. Set the base URL (for example http://localhost:1234/v1) and the model name the endpoint advertises.

Which models should I use?

For cloud providers, any current model from Anthropic, OpenAI, Google, Groq or Together works; you supply the model identifier and your key.

For local models, the trade-off is quality against hardware. An 8B model is usable for drafting from retrieved sources, which is the task here: the model is summarising your own material rather than recalling facts. Larger models produce better prose but need more memory.

Retrieval quality does not depend on the LLM at all. Finding the right source is done by the embedding model and the keyword index, both local and both fixed. The LLM only phrases the answer.

What does it cost to run?

Nothing, beyond the machine it runs on. RepliSec is free under the FSL, with no subscription, no licence server and no usage metering. If you use a cloud model you pay that provider directly, with your own key. If you use a local model you pay nothing at all.

Retrieval

Library first. Knowledge base second. Model last.

How does retrieval actually work?

Three things happen in order.

Your approved answer library is checked first. If a question closely matches an answer your team has already signed off, that answer is returned verbatim, with no model call at all. This is the fastest and most defensible path, and it is why the library gets more valuable with every questionnaire.
Otherwise the knowledge base is searched, semantically via vectors with a fallback to keyword search. Results are filtered by relevance, so a question your material does not cover returns nothing rather than the closest available paragraph.
Only then is the model asked to draft an answer from those sources, with instructions to say so when the sources are insufficient rather than fill the gap.

Every answer shows its confidence and the sources behind it. Confidence is computed from how well the retrieved material actually matched, not from the model's own opinion of its answer, which is not evidence of anything.

What is the three-tier knowledge model?

Knowledge is filed at one of three tiers, and the more specific tier wins:

Foundation: a third party's published posture, such as a cloud provider's trust centre. Controls you inherit rather than operate.
Organisation: your own policies, procedures and approved answers.
Customer-specific: commitments specific to one customer.

The rule that makes this safe: foundation knowledge never automatically becomes your answer. When you add a third party's material you declare how you rely on them. You build on them, they process data for you, or you merely hold the document. Anything undeclared is excluded from answers entirely.

Without that step a system will happily answer a question about your subprocessors using another company's subprocessor list, and present it as yours. Declaring the relationship is what keeps an inherited answer defensible, and every inherited answer carries a link back to the source so a reviewer can check it is still current.

Security & licence

Credentials, users and the licence.

How are my provider credentials stored?

API keys are encrypted with AES-GCM before being written to SQLite, using a key you supply as REPLISEC_ENCRYPTION_KEY. That key is never persisted; it lives only in the container's environment.

If you rotate or lose it, RepliSec does not fail to start. It detects that the stored credentials can no longer be decrypted, treats them as absent, and asks you to re-enter them in Settings.

Is it multi-user?

Not in this release. RepliSec is designed for an individual practitioner: no accounts, no login, no roles. Shared knowledge, approval workflows and customer workspaces are what RepliSec Teams is for.

The data model already carries the tenancy and client-scoping needed for that, and client-specific knowledge is physically isolated in its own vector collection rather than filtered at query time, so the isolation is structural rather than a WHERE clause someone can forget.

What is the licence?

The Functional Source License, version 1.1, with Apache 2.0 as the future licence (FSL-1.1-ALv2). In practice:

You can: read the source, run it, modify it, fork it, self-host it, and use it inside a commercial organisation, all free of charge.

You cannot: offer RepliSec, or a product substantially built from it, as a commercial service or product that competes with RepliSec.

Each release automatically converts to the Apache 2.0 licence two years after that release is published. The full licence text ships with the source and is published at fsl.software.

Copyright The Impact CTO Limited.

Why FSL and not MIT?

Because we want two things that are honest to state plainly. First, that anyone can inspect, run and self-host RepliSec forever, free; that is what makes a security tool trustworthy. Second, that a hosted or team edition can fund the project's development without a larger company simply relaunching our own code as a competing service. MIT provides the first but not the second. FSL provides both, and its two-year conversion to Apache 2.0 means every line we write becomes fully open source on a fixed schedule. FSL is used in production by Sentry and others; the model is sometimes called Fair Source (fair.io).

Can I contribute?

Yes, once the repository is public. Contributions are accepted under the Developer Certificate of Origin (DCO): each commit carries a Signed-off-by line certifying you have the right to submit it under the project licence, enforced automatically on pull requests. There is no separate contributor agreement to sign.

Join the Alpha

How RepliSec works under the hood.