Skip to content
Wavertex
Documentation menu

Installation

Verified with Cortex on October 2, 2026

Cortex installs on your own infrastructure. The installation sets up the web interface, the gateway and PostgreSQL with pgvector. The AI engine is optional and can be added afterwards.

Requirements

  • Docker with Compose.
  • Node 24 and pnpm 11, installed on the host machine: the setup script and the provisioning commands run on the host, not inside a container.
  • Ports 3000 (web interface), 4000 (gateway) and 5432 (PostgreSQL) free.
  • A model to talk to: a local model (Ollama, for example) or an account with a cloud provider.

If you use your own PostgreSQL instance instead of the bundled container, it must be version 18 or later, with pgvector 0.8 or later installed on the server. The bundled container (pgvector/pgvector:pg18) meets both requirements. For an external instance, the privileged bootstrap must be done before the script: the cortex_owner and cortex_gateway roles, a database owned by cortex_owner, and pgvector installed (see the “External PostgreSQL” chapter of the repository's DEPLOYMENT document). Without it, the script stops.

Install with the setup script

The setup script is meant for a first installation or an evaluation. A production deployment needs its own keys and settings: see Configuration and, in the Cortex repository, the DEPLOYMENT document.

  1. Clone the Cortex repository, then move to its root. Run git clone <repository URL>, where the URL is the address of the Cortex repository.

  2. Run the setup script:

    ./scripts/setup-dev.sh

    It asks where PostgreSQL runs (bundled container or external instance), the passwords, the ports and the interface language. It can also generate a random encryption key for you. It then writes the .env file, installs the dependencies, starts only the PostgreSQL container (or, for an external instance, checks the connection and that pgvector is present), runs the migrations, creates the tenant and the first administrator account, and offers to add an LLM destination. You can safely run it again: the values of an existing .env become the default answers.

  3. Start the full stack:

    docker compose up -d --build

    The script neither builds nor starts the web and gateway containers: this command does. With an external PostgreSQL instance, use the provided override instead (Docker Compose 2.24 or later):

    docker compose -f docker-compose.yml -f docker-compose.external-db.yml up -d --build

First start

Open http://localhost:3000 (or the web port you chose) and sign in with the email and password of the administrator account the script created. That account lands directly on the administration console.

Cortex screenshot: the sign-in page, with the SSO button and the email and password form
The sign-in page: SSO or a local account.

A destination created by the script is open to the “Employee” role only, and the account the script creates holds only the “Administrator” role: to try the chat, sign in with an employee account, or add the role to the destination. If you did not add a destination during the script, add one from the “Destinations” entry of the administration console (the “LLM Destinations” page), open to the relevant roles, before chatting: without a destination, nobody can write a message.

Enable the AI engine (optional)

The AI engine is a Python node meant to be reachable only by the gateway (every request needs its signed header; network isolation is a deployment rule). It adds:

  • named-entity recognition in DLP (DLP 1.5), for example person names;
  • detection by a local model (DLP 2), which relies on an OpenAI-compatible server you control;
  • text extraction and embeddings for the knowledge base.

Cortex works without it: pattern and secret filtering keeps applying, and no essential feature depends on it. Cortex's docker-compose.yml does not have a service for the engine yet: you build its image (docker build -t cortex-ai-engine apps/ai-engine) and run it yourself. The engine verifies the gateway's signed header with a public key, CONTEXT_SIGNING_PUBLIC_KEY.

In the .env file at the repository root (read by Compose on the host), three variables turn it on, then recreate the gateway container (docker compose up -d gateway):

AI_ENGINE_ENABLED=true
AI_ENGINE_URL=http://<engine address>:8000
CONTEXT_SIGNING_PRIVATE_KEY=<base64 Ed25519 private key>

AI_ENGINE_URL is a bare origin (scheme, host, port), with no path. If a value is invalid, the gateway refuses to start. If the engine is unreachable, the gateway keeps serving with pattern-based DLP. See Configuration for the variables.

Next