This is the multi-page printable view of this section. .
Deploy
- 1: Deploy with Docker Compose
- 2: Configuration
- 3: Models and ONNX
- 4: Performance tuning
- 5: NVIDIA CUDA
- 6: Security boundaries
- 7: Upgrade
For whoever runs Cortrix: deployment, configuration, models, and execution providers.
1 - Deploy with Docker Compose
The repository ships a Compose deployment. Here’s what it includes, how to check on it, where your data lives, and how to let other machines reach it.
If you haven’t started Cortrix yet, begin with the Quickstart.
The bundled Compose deployment is built for local evaluation. It has no authentication and listens only on the loopback address by default. It isn’t an internet-facing production setup.
What’s included
| Item | Details |
|---|---|
| Compose file | deploy/docker-compose.yml |
| Image | Built from source with deploy/Dockerfile and tagged cortrix:quickstart |
| Service | One cortrix container running cortrix-server and the Web UI |
| Port | 127.0.0.1:8420, shared by the API and the Web UI |
| Volume | cortrix-data, mounted at /data in the container |
| Execution provider | CPU for both embedding and reranking |
| Off by default | External LLM roles and the built-in Agent |
The metrics port and the built-in Agent port aren’t published to the host.
Start and stop
down keeps the volume. On later starts you can drop --build to skip rebuilding the image.
Check status
Cortrix has three health endpoints:
| Endpoint | What it tells you |
|---|---|
/api/v1/system/health/live | Whether the process is alive |
/api/v1/system/health/ready | Whether the API, the models, and the demo data are all ready |
/api/v1/health | A summary of each component |
The container’s health check allows a 30-minute start period so the first start has time to download the models.
Web UI
The Web UI shares a port with the API. Once the service is up, open http://127.0.0.1:8420/ in your browser.
Where your data lives
All persistent data is in the cortrix-data volume: model files, databases, the vector index, and uploaded files. Docker prefixes the volume name with the Compose project name, so by default it’s deploy_cortrix-data.
docker compose down --volumes deletes this volume, along with all of your data and the downloaded models.
Let other machines connect
By default, nothing outside the host can reach the service. To open it up on an isolated test network you control, set CORTRIX_PUBLISH_HOST when you start it, and preferably pick an uncommon port:
Any machine that can route to that address can then reach the Web UI and API at http://10.0.0.5:18420/.
This path has no authentication. Anyone who can reach the address gets full API access. Use it only on an isolated test network you control, never on a shared corporate network, a cloud network with other tenants, or anything internet-facing.
Setting only the port, without CORTRIX_PUBLISH_HOST, doesn’t widen what the service listens on.
Admin endpoints
Admin endpoints accept requests only from the loopback address. In a Docker deployment, a request from the host doesn’t look like loopback to the container, so it gets 403 CX_ERR_ADMIN_LOOPBACK_REQUIRED. When you need an admin endpoint, send the request from inside the container:
Next steps
2 - Configuration
Cortrix can be configured in two ways. This page explains both and walks through the settings you’re most likely to change: authentication, logging, and LLM roles. For every key, see the configuration reference.
Two ways to configure
| Method | Use it when | Template |
|---|---|---|
| YAML configuration file | You build from source and run cortrix-server directly | config.yaml.example |
| Environment variables | You deploy with Docker | deploy/.env.example |
When a setting appears in both places, the environment variable wins.
Configuration file
When you run from source, copy the template into the build directory:
Environment variables
For a Docker deployment, copy the template to .env and edit what you need:
Common variables:
| Variable | Value in the template | Purpose |
|---|---|---|
CORTRIX_DATA_DIR | /data | The data directory |
CORTRIX_HTTP_PORT | 8420 | The HTTP port |
CORTRIX_LOG_LEVEL | info | The log level |
CORTRIX_PROFILE | quickstart | quickstart is the default and is what the bundled Compose file uses. full provisions the embedding model and fails startup if it’s missing. lite explicitly turns off the embedding model and the parsers, and is for development only |
CORTRIX_EMBEDDING_EXECUTION_PROVIDER | auto | The execution provider for embedding |
CORTRIX_RERANKER_EXECUTION_PROVIDER | auto | The execution provider for reranking |
CORTRIX_WEB_UI_ENABLED | true | Whether the Web UI is on |
CORTRIX_AGENT_ENABLED | true | Whether the built-in Agent is on |
The deploy/docker-compose.yml used by the quickstart doesn’t need a .env file, and it keeps LLMs and the built-in Agent off. It reads only three variables from the environment or from deploy/.env: CORTRIX_PUBLISH_HOST, CORTRIX_HTTP_PORT, and CORTRIX_SOURCE_REVISION. Other settings in the file don’t reach the container.
Server
host defaults to the loopback address. Turn on authentication before you bind to a non-loopback address, or the server refuses to start.
There’s one exception, which the bundled Compose file relies on. Inside a container, the server can bind the container interface without authentication when CORTRIX_SERVER_ALLOW_UNAUTHENTICATED_CONTAINER_BIND is true, as long as the host port is published only to loopback.
Authentication
Running without authentication is accepted only when the server binds to the loopback address. With authentication on, the configuration looks like this:
key_hash is the SHA-256 of the key. The configuration file never holds the key itself:
Logging
LLM roles
Cortrix splits its use of LLMs into five independent roles. You configure each role separately, and a feature stays off until its role is configured.
| Role | Used for |
|---|---|
semantic_llm | Query-side semantic processing such as intent classification |
vision_llm | Refining image recognition after OCR. The model must accept image input |
agent_llm | Chat in the built-in Agent |
doc_summary_llm | Generating document summaries at ingest time |
enricher_llm | Enriching content at ingest time |
None of these roles has anything to do with the local embedding and reranking models the quickstart uses. With no LLM role configured, embedding and reranking work as usual.
Every role takes the same four fields. A role counts as configured only when provider, api_key, and model are all set:
provider can be openai, glm, claude, ollama, deepseek, or mock.
Roles use two different protocols
| Role | Called by | Protocol |
|---|---|---|
agent_llm | The built-in Agent (Python) | Each provider’s native protocol |
| The other four | cortrix-server (C++) | OpenAI-compatible only. Requests go to {base_url}/chat/completions |
That difference matters when you pick a provider. Take Claude as an example:
For
agent_llm, connect directly and don’t setbase_url:config.yamlFor the other four roles, go through an OpenAI-compatible proxy gateway and point
base_urlat it:config.yaml
OpenAI, GLM, DeepSeek, and a local OpenAI-compatible gateway work directly in every role.
Use placeholder values in documentation and examples. Keep real keys only in ignored local configuration files, and never commit them.
Next steps
3 - Models and ONNX
Cortrix runs two local models. Here’s where they come from, how they’re verified at startup, and where the files live.
Models
A Docker deployment downloads two families of local neural models into the cortrix-data volume. They aren’t baked into the image.
| Model | Role | Download size | Pinned source | Upstream and license |
|---|---|---|---|---|
| BGE-M3 | Embedding | 585,562,194 bytes | onnx-community/bge-m3-ONNX@25b9af8 | BAAI/bge-m3@5617a9f, MIT |
| bge-reranker-v2-m3 | Reranking | 587,809,994 bytes | onnx-community/bge-reranker-v2-m3-ONNX@6f5ff65 | BAAI/bge-reranker-v2-m3@953dc6f, Apache-2.0 |
The onnx-community repositories are format-conversion sources for the BAAI upstream revisions listed above. Cortrix doesn’t claim authorship of these models.
These models are independent of any LLM configuration. With no LLM role configured, embedding and reranking work as usual.
Model manifest
deploy/model-manifest.tsv is the authoritative, machine-readable record of model identity. For every model and tokenizer file it records:
- The repository, revision, and file path
- The expected byte size and SHA-256
- The upstream repository, upstream revision, and upstream license
The manifest lists four files:
| Component | Installed at |
|---|---|
embedding_model | bge-m3/model.onnx |
embedding_tokenizer | bge-m3/tokenizer.json |
reranker_model | bge-reranker-v2-m3/model.onnx |
reranker_tokenizer | bge-reranker-v2-m3/tokenizer.json |
Download and verification at startup
On the first start, the container downloads the manifest’s files into /data/models. The downloader:
- Fetches the exact revision and path in the manifest.
- Rejects symbolic links.
- Checks the byte size and SHA-256.
- Installs each file atomically.
If anything doesn’t match, or a download fails, the container doesn’t report ready. Readiness also requires both models to finish loading and the demo data to finish importing. The quickstart never falls back silently to a stub embedder or reranker.
Later starts reuse the models already in the volume.
Start without access to Hugging Face
The first start downloads the model files from Hugging Face. On a machine that can’t reach it, copy the files in before the first start. The downloader verifies every file it finds in /data/models against the manifest and downloads only what is missing or doesn’t match, so a complete, valid copy means nothing is downloaded.
On a machine where the quickstart has already started once, copy the model directory out of the container. The container can be stopped. Make sure
./modelsdoesn’t exist yet, or the files land one level too deep:The
modelsdirectory holdsbge-m3/,bge-reranker-v2-m3/, andMANIFEST.tsv, about 1.17 GB in total.Move the
modelsdirectory to the machine that has no access.On that machine, create the container without starting it, copy the directory in, hand the files to the user the service runs as, and then start:
docker cpcreates the copied files as root, and the service runs ascortrix. Without thechown, the service can read the models but can never replace one, so the container would exit at start the first time a file fails verification or a later release pins a different model revision.
The log shows that the cached files were verified and nothing was downloaded:
A copied file that fails the size or SHA-256 check isn’t used. The downloader tries to fetch it again, and without network access it can’t download a replacement, so the container exits without starting the service. Copy the directory again from a machine where the quickstart reports ready.
Building the image still needs network access, for the base images and the build dependencies. This section covers only the model download at first start.
Remove the cached models
This deletes the whole volume, including your data, not just the models.
Model settings when you run from source
When you run from source, the configuration file sets the model paths:
dimensionis fixed at 1024 and can’t be changed.- An empty
embedding.model_pathis the only explicit stub mode. If the path is set but the model is missing or invalid, the server fails to start instead of degrading to a stub. - An empty
reranker.model_direxplicitly selects the stub reranker. If the path is set, the model and tokenizer must be valid.
What the quickstart doesn’t include
The Docker quickstart covers only text files, BGE-M3 embedding, and bge-reranker-v2-m3 reranking. It doesn’t install or validate PDF, DOCX, images, OCR, query-complexity routing, external LLM roles, or the built-in Agent. Those are separate features. Check Compatibility and status before you rely on them.
Upgrade ONNX Runtime
The repository pins the ONNX Runtime version. The steps and verification requirements for upgrading it are written for maintainers. See ONNX Runtime upgrade and rollback.
Next steps
4 - Performance tuning
A handful of settings affect Cortrix’s performance. Learn which stage each one acts on and how to measure its effect on your own data.
Which way to turn a setting depends on your task and your data. The numbers on this page only illustrate direction. Measure on your own data before you change a default.
Measure first
Every query response includes the latency the server measured:
Change one variable at a time, repeat the same set of queries several times, and compare the median meta.latency_ms. Check result quality too: faster isn’t the same as better.
Add ?explain=true to see which retrieval paths a query used. See Query and rerank.
Settings at a glance
| Setting | Where | Default | Affects |
|---|---|---|---|
rerank | Query request | true | Query latency and result ordering |
top_k | Query request | 10 | How many results come back, and the candidate pool size |
retrieval.candidate_multiplier | Configuration file | 3 | Candidate pool size |
retrieval.max_candidates | Configuration file | 50 | The candidate pool ceiling, and so the recall ceiling |
embedding.execution_provider | Configuration file | auto | Where embedding runs |
reranker.execution_provider | Configuration file | auto | Where reranking runs |
server.thread_count | Configuration file | 4 | The server’s worker threads |
spc.worker_count | Configuration file | 2 | How many documents are processed in parallel |
spc.embedding_batch_size | Configuration file | 1 | Blocks embedded per batch |
spc.onnx_intra_threads | Configuration file | 4 | Intra-op threads for ONNX inference |
spc.onnx_inter_threads | Configuration file | 1 | Parallel ONNX inferences |
The configuration file defaults come from config.yaml.example in the repository.
Queries
Reranking
Reranking is the single switch with the biggest effect on query latency. When it’s on, Cortrix scores each retrieved candidate with the cross-encoder model bge-reranker-v2-m3.
As a rough illustration, here is one measurement taken while writing this page. It isn’t a published benchmark, and it isn’t in the repository. On the quickstart service, with 3 short documents and CPU inference in Docker on an Apple silicon Mac, the median over 8 queries per setting was:
| Setting | Median latency_ms |
|---|---|
rerank: true | 242 |
rerank: false | 52 |
The measurements published in the repository show that on the Quora corpus (522,931 documents, a 32-core CPU, no GPU, serial queries), mean query latency goes from 1.7 seconds without reranking to 19.0 seconds with it.
Whether reranking is worth that cost depends on the kind of task:
| Kind of task | Examples | Recommendation |
|---|---|---|
| Questions and answers | Documentation search, finding solutions in support tickets, grounding a RAG answer | Leave it on |
| Finding identical or duplicate items | Duplicate-question detection | Turn it off |
In the published measurements, the three question-answering datasets (SciFact, NFCorpus, FiQA) gained 0.013 to 0.059 nDCG@10 with reranking on, while duplicate-question detection (Quora) dropped from 0.5003 to 0.2031. The reranker optimizes for “relevant,” and that kind of task is looking for “the same.”
For neighboring cases such as duplicate tickets, similar products, or “find similar” features, the same problem is a hypothesis, not a measurement. Test it on your own data.
To turn reranking off, set "rerank": false on each query.
Only the rerank flag on the query request takes effect today. The namespace-level reranker_config is accepted, but the query path doesn’t read it yet. See cortrix/cortrix#75. For a workload that shouldn’t be reranked, every request needs to pass "rerank": false explicitly.
For the measurement conditions and full data, see When to rerank and Benchmark evidence.
Candidate pool size
Cortrix fetches more candidates than top_k, then ranks and truncates. The number of candidates is:
- A larger
top_kmeans more candidates and more content returned. max_candidatesis a hard ceiling. On a large corpus, relevant documents can rank below 50, so raisingmax_candidatesis the only way to lift the recall ceiling.
You can also override these with the CORTRIX_RETRIEVAL_CANDIDATE_MULTIPLIER and CORTRIX_RETRIEVAL_MAX_CANDIDATES environment variables.
Query scope
List only the namespaces you actually need in namespaces. ["*"] queries every namespace you have access to, up to 100.
Time limits
A query request has no time budget of its own on this release. A query over several namespaces has two default wait limits in the step that collects the namespaces’ results: that step waits up to 5 seconds for each namespace in turn, counted from when it reaches that namespace, and stops waiting altogether 30 seconds after it started. A namespace it stops waiting for is listed among the failed namespaces with CX_ERR_NS_TIMEOUT, and the results from the other namespaces still come back.
These limits bound waiting, not work. A namespace can take longer than 5 seconds and still succeed when the collection reaches it later. The 30 seconds are not an end-to-end limit for the request: waiting for a free worker, RAG-Fusion and reranking come on top. The work of a namespace the collection stopped waiting for is not cancelled. A query over a single namespace has no wait limit.
Execution providers
The embedding model and the reranker each have an execution_provider setting. The values are auto, cpu, coreml, and cuda:
The matching environment variables are CORTRIX_EMBEDDING_EXECUTION_PROVIDER and CORTRIX_RERANKER_EXECUTION_PROVIDER. The quickstart pins both to cpu.
The readiness check shows which execution provider is actually in use:
active_ep is the provider in use. A fallback of true means the configured provider wasn’t available and Cortrix fell back.
Using an NVIDIA GPU on Linux needs a separate image. See NVIDIA CUDA. The CUDA document in the repository is a deployment guide and doesn’t include performance data.
Ingestion
After upload, a document is parsed, chunked, and embedded. These settings control how much of that pipeline runs in parallel:
| Setting | Purpose |
|---|---|
worker_count | Threads processing documents in parallel. 2 to 4 is recommended |
embedding_batch_size | Blocks sent to the embedding model per batch |
onnx_intra_threads | Threads used inside a single ONNX inference |
onnx_inter_threads | ONNX inferences that run in parallel |
chunk_size | The target number of tokens per text block. Smaller blocks mean more blocks per document |
These are configuration-file keys. They have no environment-variable override.
The readiness check reports the current queue depth and worker count under spc_pipeline:
Server
server.thread_countis the number of worker threads handling requests. The recommended value is your CPU core count. You can override it withCORTRIX_SERVER_THREADS.
What these numbers do and don’t tell you
The measurements published in the repository cover retrieval quality at top_k=10 and mean latency under serial queries. They say nothing about production latency or capacity under concurrency, or about end-to-end answer quality.
This page doesn’t recommend values for thread counts, batch size, or execution providers, because the repository has no published controlled measurements for them. Measure those on your own hardware and data, using the method above, before you settle on values.
Next steps
5 - NVIDIA CUDA
Build and run the Cortrix CUDA image, then confirm that the models are really running on the GPU.
The default deploy/Dockerfile and deploy/docker-compose.yml are a CPU deployment. CUDA is turned on only when you build deploy/Dockerfile.cuda and layer deploy/docker-compose.cuda.yml on top.
This page is adapted from the CUDA execution provider runbook and hasn’t been tested on a GPU machine. It’s a deployment guide and contains no performance data. Complete the verification steps on your target machine before you treat CUDA as verified.
Prerequisites
- A Linux x86_64 host and container architecture.
- An NVIDIA GPU and a compatible driver.
- Docker, Docker Compose, and NVIDIA Container Toolkit configured for Docker.
The image runtime is CUDA 11.8 and cuDNN 8 on Ubuntu 22.04, with the repository-pinned ONNX Runtime 1.17.1 GPU build.
Host driver requirements:
| Host NVIDIA driver | Notes |
|---|---|
>= 520.61.05 | The required baseline, and the recommended version for deployment |
>= 450.80.02 and < 520.61.05 | NVIDIA documents compatibility in this range, with limitations. Cortrix doesn’t treat this range as validated |
< 450.80.02 | Below the compatibility floor for CUDA 11.8. Don’t use it |
Check the host before you build:
uname -m must print x86_64, and nvidia-smi must list the GPU you intend to use.
Execution provider values
Embedding and reranking each choose an execution provider independently, from the same set of values:
| Value | Behavior in the CUDA image |
|---|---|
auto | Try CUDA first. If it fails, record the reason and create a fresh CPU-only session |
cpu | Use the CPU without trying CUDA |
cuda | Require CUDA. A failure aborts startup, with no CPU fallback |
coreml | For builds on Apple platforms. Not available in the Linux CUDA image |
Environment variables take precedence over the YAML configuration. Values aren’t case-sensitive, but lowercase is recommended.
Steps
Run every command from the root of the repository.
Prepare the environment file
At a minimum, confirm these settings:
The CUDA override file passes these values into the container. When the profile is full, the Quick Start demo data isn’t loaded.
To use only one GPU, set NVIDIA_VISIBLE_DEVICES to its index or UUID. Cortrix needs only the compute and utility capabilities.
Build the image
The build is restricted to linux/amd64, and model files aren’t baked into the image.
Start the stack
Follow the startup log until the service is healthy:
Verify
Don’t conclude that CUDA is in use from the image name or from GPU visibility alone. Check each of these.
Check that the container sees the GPU
Only the GPUs selected by NVIDIA_VISIBLE_DEVICES should be listed.
Check the runtime libraries
This command succeeds only when there are no missing dependencies.
Check the active execution provider
Look at components.embedding_execution_provider and components.reranker_execution_provider:
| Situation | What you see |
|---|---|
| CUDA is working | active_ep is cuda |
auto fell back to the CPU | The service is still ready, but fallback is true, active_ep is cpu, and preferred_ep is cuda |
| The explicit setting and reality don’t match | The service isn’t ready, and policy_mismatch is true |
| No model is configured | model_configured is false and active_ep is stub |
Check the metrics
The metrics port, 9091, is open only inside the container, so query it from there:
A CUDA build includes this line:
Require the GPU
A typical CUDA deployment keeps both components on auto. If you’d rather have startup fail than fall back to the CPU when GPU initialization fails, change that component to cuda and recreate the service:
Roll back to CPU
To switch back to the default CPU image and keep the data volume:
Don’t add --volumes to down unless you really mean to delete your data.
To keep the CUDA image and just use the CPU for now, set both execution provider variables to cpu and recreate the service.
Troubleshooting
| Symptom | What to do |
|---|---|
| Docker reports that no GPU driver is available | Confirm nvidia-smi works on the host, and that NVIDIA Container Toolkit is installed and configured for Docker |
| The container is rejected before the entrypoint runs | Check the Docker daemon log for an NVIDIA_REQUIRE_CUDA or driver-version constraint error, and upgrade the host driver. Don’t set NVIDIA_DISABLE_REQUIRE=true to bypass the check |
| The pre-flight check can’t see a GPU | Check the value of NVIDIA_VISIBLE_DEVICES, and that NVIDIA_DRIVER_CAPABILITIES includes compute,utility |
ldd reports CUDA or cuDNN libraries as not found | Rebuild from deploy/Dockerfile.cuda and confirm the runtime stage is the CUDA 11.8 and cuDNN 8 image |
Next steps
6 - Security boundaries
Read this before you deploy Cortrix anywhere beyond your own machine. It covers what Cortrix can and can’t guarantee about security today.
Cortrix is in pre-release. Tenant isolation, access control, and log redaction are in development. API key permissions are off by default: Cortrix checks them only with authentication on. API key configuration exists, but its behavior hasn’t been verified for this documentation. See Compatibility and status. Until these are available, deploy Cortrix only on a network you control.
Default protections
The bundled Compose deployment is configured this way in v1.0.0-rc.2:
- It listens only on the loopback address. The Compose deployment publishes the API at
127.0.0.1:8420, so other machines can’t reach it. - Admin endpoints accept loopback requests only. An admin request from a non-loopback address gets 403
CX_ERR_ADMIN_LOOPBACK_REQUIRED. - The metrics port isn’t published. It’s reachable only from inside the container.
- External LLMs are off by default. The quickstart sends no documents or queries to any external LLM service.
The configuration template also states that running without authentication is accepted only when the server binds to the loopback address, and that authentication must be on before the server binds to a non-loopback address.
With authentication off
The bundled configuration ships with authentication off. In that mode every request is treated as an admin of the default tenant: it can read and write every namespace, call the tenant, member, and maintenance endpoints, and restore or purge deleted documents. The server accepts this only on the loopback address or a container-internal bind published only to loopback, so anyone who can reach that port has full access.
What not to do
- Don’t expose an unauthenticated service to a network you don’t control. Access opened with
CORTRIX_PUBLISH_HOSThas no authentication at all, and is only for an isolated test network you control. - Don’t use a local run with authentication off to prove that access control works. With authentication off, denial behavior for RBAC, tenant isolation, ACLs, and quotas can’t be demonstrated.
- Don’t assume logs are redacted. Startup and runtime logs can contain sensitive content. Check them yourself before you collect or share them.
- Don’t put keys in files that get committed. Keep real API keys only in ignored local configuration.
Authentication schemes
Cortrix authenticates requests with an API key, sent in the X-API-Key header. The configuration file stores an API key as its SHA-256 hash. To set one up, see Configuration.
Before production
At a minimum, verify these in your target environment:
- Authentication mode and credential handling
- Tenant isolation and RBAC behavior
- Namespace ACLs and quotas
- Logging and redaction
- Data persistence and backup strategy
- Deployment topology and resource limits
Treat anything you haven’t verified as not ready.
Report a vulnerability
Report suspected vulnerabilities privately to security@cortrix.ai. Don’t open a public issue for an unpatched vulnerability, credentials, customer data, or details of exploitable infrastructure.
Include:
- The affected 40-character commit hash
- The impact
- A minimal reproduction
- Sanitized evidence
Don’t include secrets unless the security response team explicitly asks for them and gives you a secure way to send them.
The team acknowledges receipt within 5 business days. An acknowledgment means the report has been received and routed. It isn’t a promise that analysis, a fix, or a release will be finished in that time.
Don’t disclose the vulnerability publicly before a fix is available or before a disclosure date both sides agree on.
Until the first stable release, security support covers only the latest commit on the default branch.
Next steps
7 - Upgrade
Before you move from v1.0.0-rc.1 to v1.0.0-rc.2, here’s what to check first, what to verify afterward, and how to roll back.
RC2 is a new pre-release. Back up your persistent data and validate RC2 against a copy before you change an existing environment.
Before you upgrade
- Read Compatibility and status and confirm the current status of the capabilities you depend on.
- Record your existing source revision, configuration, model files, database path, and rollback procedure.
- In an isolated environment, rerun your API, SDK, MCP, deployment, and persistence smoke tests against the exact RC2 tag.
- Keep treating your source documents as authoritative until you’ve verified indexing, query behavior, deletion, and rollback.
Changes to verify
Task lifecycle and persistent data
RC2 changes a lot in the asynchronous task lifecycle. Verify task submission, terminal states, resubmission, cancellation races, cleanup scheduling after a restart, namespace-scoped task identity, and repeated or same-content batch uploads.
There’s no new SQL migration file to apply by hand between v1.0.0-rc.1 and RC2. Startup still creates or adjusts indexes and task state, though, so this is no substitute for a backup or for an upgrade test against a copy.
Query and reranking
- When the reranker doesn’t suit your task, pass
rerank=falseon each request. - Don’t rely on the namespace-level reranker setting to turn reranking off. The query path doesn’t read it yet.
See Performance tuning.
MCP
- The local MCP server supports both the modern stdio discovery path and the legacy initialization handshake.
- Session and trace identity are passed through to the Cortrix server.
- Verify client and server API compatibility before you replace an existing MCP environment. Local stdio is still the only public transport.
Deployment
- Docker Compose still listens only on the loopback address by default.
- Publishing to a LAN address is an explicit opt-in, meant only for isolated test networks.
- After upgrading, rerun the readiness check and the reranked query from the Quickstart.
License change
Cortrix-authored RC2 material is licensed under Apache-2.0. Release objects from the historical v1.0.0-rc.1 remain under AGPL-3.0-only, and third-party material keeps its own license. Before you redistribute a mixed or modified package, review LICENSE, NOTICE.md, and CONTRIBUTING.md in the repository.
Reading the benchmarks
- The RC2 retrieval evidence is the pinned four-corpus CPU measurement bundle. See Benchmark evidence.
- Don’t compare the 2,000-query Quora subset with a result over the full query set.
- Don’t read the published CPU latency as production capacity under concurrency.
Roll back
- Stop the RC2 environment.
- Restore the RC1 configuration and data backup you recorded.
- Check out the immutable
v1.0.0-rc.1tag.
Don’t reuse a database that RC2 has opened unless you’ve run a rollback test on that same copy and confirmed it’s compatible.