Quickstart | nivq

nivq is a single container. To run, it needs to reach a PostgreSQL (with pgvector) and a Redis/Valkey, plus a key to encrypt the credentials it stores — that's it. Everything else has a sensible default.

There are two ways to go:

Docker Compose — brings up Postgres and Redis for you too. Fastest if you're starting from scratch.
A single docker run — if you already have a Postgres and a Redis, just pull the image and point it at them.

Both read the same environment variables; the only difference is how you pass them.

Pull the image

nivq is a private image (ghcr.io/nivorbit/images/nivq). Log in with a token, then pull:

Shell

echo "<token>" | docker login ghcr.io -u <username> --password-stdin
docker pull ghcr.io/nivorbit/images/nivq:0.2.4

No token yet? Ask the Nivorbit team or email [email protected].

No registry access

On a network with no registry access? Skip the login. Nivorbit gives you the image as a tarball — load it: docker load -i nivq-0.2.4.tar

The settings nivq reads

You configure nivq with environment variables. Only a handful are required to boot:

Variable	What it does
`NIVQ_DATASOURCE_URL`	Postgres JDBC URL (with `pgvector`)
`NIVQ_DATASOURCE_USERNAME` / `NIVQ_DATASOURCE_PASSWORD`	Postgres credentials
`NIVQ_REDIS_HOST` / `NIVQ_REDIS_PORT`	Redis/Valkey address
`NIVQ_ENCRYPTION_KEY_V1`	32-byte base64 key that encrypts stored secrets (`openssl rand -base64 32`) — back it up
`NIVQ_PLATFORM_LLM_PROVIDER` / `NIVQ_PLATFORM_LLM_API_KEY`	The platform LLM that runs lightweight internal tasks
`NIVQ_BOOTSTRAP_ADMIN_USERNAME` / `NIVQ_BOOTSTRAP_ADMIN_PASSWORD`	A local admin sign-in for the first run — no IdP setup needed
`BACKEND_URL` / `FRONTEND_URL`	Public URLs reached from the browser

How you pass them is up to you — a .env file for Compose, -e flags for a single container, or values injected by a secrets manager. The full list is in Configuration.

Production mode is the default

The image always runs in production mode — dev-only endpoints stay locked out of the box. There's no mode or profile flag to set.

Guard the encryption key

Losing NIVQ_ENCRYPTION_KEY_V1 makes every stored credential unrecoverable. Back it up in a secrets manager and never commit it.

Path A — Docker Compose

Starting from scratch, Compose brings up nivq alongside its two datastores. Create a directory and drop in this docker-compose.yml:

YAML

services:
  postgres:
    image: pgvector/pgvector:pg18
    environment:
      POSTGRES_DB: nivq
      POSTGRES_USER: nivq
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - nivq-pg:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U nivq"]
      interval: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    volumes:
      - nivq-redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 10

  nivq:
    image: ghcr.io/nivorbit/images/nivq:0.2.4
    depends_on:
      postgres: { condition: service_healthy }
      redis: { condition: service_healthy }
    env_file: .env          # reads settings from here — see the example below
    ports:
      - "8080:8080"
    restart: unless-stopped

  # The browser UI. A static app pointed at the API; see Web client for details.
  nivq-web:
    image: ghcr.io/nivorbit/images/nivq-web:0.2.2
    depends_on: [nivq]
    environment:
      # The API URL as reached from the browser (must match BACKEND_URL).
      NIVQ_API_BASE_URL: http://localhost:8080
    ports:
      - "3000:8080"          # serve the UI at FRONTEND_URL (http://localhost:3000)
    restart: unless-stopped

volumes:
  nivq-pg:
  nivq-redis:

docker-compose.ymlOr download it directly.

Put the settings next to it in a .env:

Shell

POSTGRES_PASSWORD=a-strong-value
NIVQ_DATASOURCE_URL=jdbc:postgresql://postgres:5432/nivq
NIVQ_DATASOURCE_USERNAME=nivq
NIVQ_DATASOURCE_PASSWORD=a-strong-value
NIVQ_REDIS_HOST=redis
NIVQ_REDIS_PORT=6379

NIVQ_ENCRYPTION_KEY_V1=your-base64-32-bytes   # openssl rand -base64 32

NIVQ_PLATFORM_LLM_PROVIDER=anthropic
NIVQ_PLATFORM_LLM_API_KEY=sk-...

NIVQ_BOOTSTRAP_ADMIN_USERNAME=admin@example.com   # must be an email
NIVQ_BOOTSTRAP_ADMIN_PASSWORD=a-long-passphrase

BACKEND_URL=http://localhost:8080
FRONTEND_URL=http://localhost:3000

nivq.envDownloads as nivq.env — rename it to .env and fill in your values.

Bring it up:

Shell

docker compose up -d
docker compose logs -f nivq

The first boot runs database migrations, so give it a few seconds. The UI comes up at http://localhost:3000 — see Web client for how it's configured and how sign-in is wired.

Path B — A single `docker run`

If you already have a Postgres (with pgvector) and a Redis, run the image directly and point it at them. Settings come in as -e flags instead of a .env:

Shell

docker run -d --name nivq -p 8080:8080 \
  -e NIVQ_DATASOURCE_URL=jdbc:postgresql://my-postgres:5432/nivq \
  -e NIVQ_DATASOURCE_USERNAME=nivq \
  -e NIVQ_DATASOURCE_PASSWORD=a-strong-value \
  -e NIVQ_REDIS_HOST=my-redis -e NIVQ_REDIS_PORT=6379 \
  -e NIVQ_ENCRYPTION_KEY_V1="$(openssl rand -base64 32)" \
  -e NIVQ_PLATFORM_LLM_PROVIDER=anthropic -e NIVQ_PLATFORM_LLM_API_KEY=sk-... \
  -e NIVQ_BOOTSTRAP_ADMIN_USERNAME=admin@example.com \
  -e NIVQ_BOOTSTRAP_ADMIN_PASSWORD=a-long-passphrase \
  -e BACKEND_URL=http://localhost:8080 -e FRONTEND_URL=http://localhost:3000 \
  ghcr.io/nivorbit/images/nivq:0.2.4

Prefer to keep them in a file? Pass the same set with --env-file your.env.

Then run the UI container alongside it, pointed at the API:

Shell

docker run -d --name nivq-web -p 3000:8080 \
  -e NIVQ_API_BASE_URL=http://localhost:8080 \
  ghcr.io/nivorbit/images/nivq-web:0.2.2

Check it's up

Shell

curl http://localhost:8080/actuator/health
# {"status":"UP"}

Activate the licence

nivq boots into activation-pending — up, but locked except for sign-in and the licence endpoints. Read the host fingerprint and upload a licence; it's stored in the database, so this is a one-time step:

Shell

# deployment fingerprint to send to Nivorbit (for a machine-bound licence)
curl http://localhost:8080/v1/license/fingerprint
#  → NIVQ-FP-XXXXX-XXXXX-XXXXX-XXXXX

# once Nivorbit returns license.jwt, upload it — no restart needed
curl -F "[email protected]" http://localhost:8080/v1/license/upload

Details — including machine binding and air-gapped flows — are in Licensing & activation.

You're set

Open nivq at http://localhost:3000, sign in with the bootstrap admin credentials from your .env, create your first workspace, then add an agent connected to one of your databases. Now you can ask your data a question.

Wire real sign-in when you're ready

The bootstrap admin is a first-run account. For your team, configure Google, Microsoft, GitHub, or any OIDC provider per Authentication — then clear the two bootstrap variables (or keep them sealed as a break-glass login).

Next steps

See every setting in Configuration, harden it for production in Production hardening, or — if you're deploying to a Kubernetes cluster — head to Kubernetes (Helm).

Pull the image

The settings nivq reads

Path A — Docker Compose

Path B — A single docker run

Check it's up

Activate the licence

You're set

Path B — A single `docker run`