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:1.0.0

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-1.0.0.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:?Set POSTGRES_PASSWORD in .env — any strong value}
    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:1.0.0
    depends_on:
      postgres: { condition: service_healthy }
      redis: { condition: service_healthy }
    env_file: .env          # reads settings from here — see the example below
    environment:
      # Reuses POSTGRES_PASSWORD above — one password to set, not two.
      NIVQ_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD}
      # Required values fail fast with a clear message instead of a crash-loop
      # when .env still has blanks. Fill them in .env, not here.
      NIVQ_ENCRYPTION_KEY_V1: ${NIVQ_ENCRYPTION_KEY_V1:?Set NIVQ_ENCRYPTION_KEY_V1 in .env — generate with openssl rand -base64 32}
      NIVQ_PLATFORM_LLM_API_KEY: ${NIVQ_PLATFORM_LLM_API_KEY:?Set NIVQ_PLATFORM_LLM_API_KEY in .env — your LLM provider API key}
      NIVQ_BOOTSTRAP_ADMIN_PASSWORD: ${NIVQ_BOOTSTRAP_ADMIN_PASSWORD:?Set NIVQ_BOOTSTRAP_ADMIN_PASSWORD in .env — first-run admin password}
    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:1.0.0
    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. The quickest way generates strong, unique secrets for you — leaving only your LLM key to paste:

Shell

cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -base64 24)
NIVQ_ENCRYPTION_KEY_V1=$(openssl rand -base64 32)
NIVQ_PLATFORM_LLM_PROVIDER=anthropic
NIVQ_PLATFORM_LLM_API_KEY=
NIVQ_BOOTSTRAP_ADMIN_USERNAME=admin@example.com
NIVQ_BOOTSTRAP_ADMIN_PASSWORD=$(openssl rand -base64 18)
BACKEND_URL=http://localhost:8080
FRONTEND_URL=http://localhost:3000
NIVQ_DATASOURCE_URL=jdbc:postgresql://postgres:5432/nivq
NIVQ_DATASOURCE_USERNAME=nivq
NIVQ_REDIS_HOST=redis
NIVQ_REDIS_PORT=6379
EOF

Then, two things: paste your provider key into NIVQ_PLATFORM_LLM_API_KEY (left blank on purpose — startup stops with a clear message until you do), and note the generated admin password with grep NIVQ_BOOTSTRAP_ADMIN_PASSWORD .env. Back up NIVQ_ENCRYPTION_KEY_V1 — lose it and every stored credential is unrecoverable.

Never reuse these values across deployments or commit them. Each environment gets its own freshly generated secrets.

Prefer to fill it in by hand? Here is every setting, explained:

Shell

# NivQ settings — fill in every empty value under "Required".
# `docker compose up` refuses to start (with a clear message) until they are set.

# ── Required ─────────────────────────────────────────────────────────────────

# Password for the bundled Postgres — NivQ connects with the same value.
# Any strong value; pick it once (changing it later means resetting the DB volume).
POSTGRES_PASSWORD=

# Required — a 32-byte base64 key that encrypts the credentials NivQ stores.
# Generate one and paste it after the = below:  openssl rand -base64 32
# (Or use the one-command .env generator in the Quickstart, which fills this in.)
# Back it up — if this key is lost, every stored credential is unrecoverable.
NIVQ_ENCRYPTION_KEY_V1=

# The platform LLM — runs internal tasks and serves every non-Enterprise plan.
# Provider and model are optional: leave them unset to use the defaults shown
# below. To change them, uncomment the line — an empty value overrides the
# default (and fails boot), so don't leave them blank.
# NIVQ_PLATFORM_LLM_PROVIDER=anthropic
# NIVQ_PLATFORM_LLM_MODEL=claude-haiku-4-5-20251001
NIVQ_PLATFORM_LLM_API_KEY=

# First-run admin sign-in for the web UI (username must be an e-mail address).
# Wire your real SSO later — see the Authentication docs.
[email protected]
NIVQ_BOOTSTRAP_ADMIN_PASSWORD=

# ── Public URLs ──────────────────────────────────────────────────────────────

# As reached from the browser. The localhost defaults work for a trial on one
# machine; in production set your real domains (e.g. https://nivq-api.acme.com).
# Note: the BACKEND_URL host is the domain a domain-bound licence is issued for —
# you'll share it with Nivorbit when requesting your licence.
BACKEND_URL=http://localhost:8080
FRONTEND_URL=http://localhost:3000

# ── Wired to the bundled compose file (leave as-is) ──────────────────────────

NIVQ_DATASOURCE_URL=jdbc:postgresql://postgres:5432/nivq
NIVQ_DATASOURCE_USERNAME=nivq
NIVQ_REDIS_HOST=redis
NIVQ_REDIS_PORT=6379

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

Only the values under Required need editing. Leave one blank and docker compose up refuses to start with a message naming the variable — no silent crash-loops.

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:1.0.0

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:1.0.0

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. The licence is stored in the database, so this is a one-time step.

Easiest path: open the UI at http://localhost:3000. The first-run activation screen shows your deployment identity and a Share with Nivorbit button that opens a ready-to-send licence request e-mail.

Prefer the terminal? Read the deployment identity:

Shell

curl http://localhost:8080/v1/license/fingerprint
# → {"fingerprint":"NIVQ-FP-XXXXX-XXXXX-XXXXX-XXXXX","backendHost":"api.acme.com"}

E-mail both values to [email protected] — the link opens a prefilled request. fingerprint identifies this machine; backendHost is the host of your BACKEND_URL, the domain a domain-bound licence is issued for.

Shell

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

Details — including machine binding, domain 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`