Quickstart
In this quickstart you’ll start Cortrix v1.0.0-rc.2 on your machine with Docker and run a reranked query against the bundled demo document. The whole path uses real local embedding and reranking models, and you don’t need a key for any LLM service.
If you’d rather have an AI agent run these steps, see Install with an AI agent.
Prerequisites
- Git
- Docker with Docker Compose
curl- Enough disk space for the image, the build cache, and about 1.17 GB of model files
You don’t need a .env file, an LLM provider key, model tooling on the host, or any manual model download or conversion.
Steps
Clone and start
The first start builds the image from source and downloads the model files into the cortrix-data volume (its full name in Docker is deploy_cortrix-data). Later starts reuse that volume.
The command returns only when the service is ready. It ends with:
How long the first start takes depends on your machine and network. On an Apple silicon Mac with 5 CPUs assigned to Docker, the image build took about 6 minutes and the model download took under a minute.
If you see docker: unknown command: docker compose, the Compose plugin isn’t installed. If you have the standalone version, replace docker compose with docker-compose in each command.
Check readiness
status should be ready, and every component’s status should be ok:
Compose reports the service healthy only once the API, the embedding model, the reranker model, and the demo document are all ready. If a model download hits a missing file, a size or checksum mismatch, a symbolic link, or a download error, it fails outright rather than starting with incomplete models.
Run a reranked query
The response should include content from quickstart-demo.txt and a numeric rerank_score. Here is a real response, with metadata shortened:
Identifiers, latency, and scores will differ on your machine.
Stop or reset
To stop the service and keep your data and the downloaded models:
To remove the data and models as well:
--volumes deletes the cortrix-data volume. The next start downloads about 1.17 GB of models again.
What this path verifies
The quickstart:
- Builds the local Docker image from the checked-out source.
- Downloads pinned versions of the BGE-M3 embedding model and the bge-reranker-v2-m3 reranker.
- Publishes only the API, at
127.0.0.1:8420. The metrics port and the built-in Agent port aren’t published. - Keeps every external LLM role and the built-in Agent turned off.
- Sends a query with a plural
namespacesarray andrerank=true, and gets back source-backed demo content with numeric rerank scores.
It does not cover PDF, DOCX, images, OCR, authentication, internet-facing deployment, or retrieval-quality benchmarks, and it doesn’t establish production readiness.
The quickstart service has no authentication. By default Compose publishes it only on the host’s loopback address, so other machines can’t reach it. Don’t treat it as an internet-facing deployment.
Model provenance and integrity
deploy/model-manifest.tsv in the repository pins the repository, revision, path, expected size, SHA-256, upstream repository, upstream revision, and upstream license for every downloaded file.
| Purpose | Model | Source |
|---|---|---|
| Embedding | onnx-community/bge-m3-ONNX | Derived from BAAI/bge-m3 |
| Reranking | onnx-community/bge-reranker-v2-m3-ONNX | Derived from BAAI/bge-reranker-v2-m3 |
At startup, Cortrix downloads each manifest entry, verifies its size and SHA-256, and installs it atomically. If anything doesn’t match, the service doesn’t report ready.
Next steps
- Core concepts: understand the namespace, blocks, and query you just used.
- Choose an access path: connect to the running service through MCP or the Python SDK.
- Compatibility and status: see the current status of every capability.