KDB.AI Server Setup

This page details the steps to set up KDB.AI Server using the standard kdbai-db image. For GPU-accelerated workloads using NVIDIA cuVS and CAGRA, refer to the Nvidia cuVS/CAGRA integration guide.

Before continuing, ensure you have completed Prerequisites.

License change: KDB-X license now required

KDB.AI Server is now powered by KDB-X. A KDB-X license is required to run kdbai-db.

Trial users upgrading from kdbai-db 1.x: You must obtain a KDB-X community license to run this image. Existing data is fully compatible and no other changes are required. Refer to Prerequisites for details on obtaining a community license.
Commercial users upgrading from kdbai-db 1.x: You must use a KDB-X license to run this image. Existing data is fully compatible and no other changes are required. Contact support@kdb.ai if you need assistance obtaining a new license.
KDB-X community license holders: Your community license can now be used with KDB.AI Server. If it is installed at $HOME/.kx/kc.lic, it is ready to use – no action required.

Hardware requirements

KDB.AI Server works on Intel, AMD, ARM, and Apple CPUs that meet the following specifications:

Intel CPUs that support AVX2 instructions (Haswell architecture).
AMD CPUs that support AVX2 instructions (Zen architecture).
ARM (aarch64) CPUs that support NEON instructions.
Apple M-series CPUs.

KDB.AI Server supports Linux ARM-based CPUs via Docker and on Apple Silicon via Docker desktop or Rancher desktop.

Software requirements

KDB.AI Server can be run using Docker, Rancher Desktop, or Podman, depending on your operating system and environment.

Container platform

Container platform	When to use it	OS compatibility	Notes
Docker Desktop	Default and recommended option for most users.	Linux, macOS (Intel & Apple Silicon), Windows	Easiest setup; standard commands; broadest support.
Rancher Desktop	Open-source alternative to Docker Desktop.	Linux, macOS (Intel & Apple Silicon), Windows	Enable dockerd (moby) and recommended VM settings.
Podman	Enterprise Linux environments (for example, RHEL) or Docker-less setups.	Linux (native), macOS (via VM), Windows (via WSL 2)	Podman CLI is a drop-in replacement for Docker commands.

Rancher Desktop configuration

To use docker CLI commands, switch the container engine to dockerd (moby) under: General > Preferences > Container Engine > General.

For Rancher desktop on Apple Silicon, we recommend the following setup:

Go to Preferences > Virtual Machine.
In the Volumes tab > tick virtiofs as Mount type.
Emulation tab > select VZ as the Virtual Machine Type.

OS requirements

Requirement	Details
Linux kernel	Version 4.18.0+
Supported distros	CentOS 8+, RHEL 8+, Ubuntu 18.04+
Windows	Use Windows Subsystem for Linux (WSL) instead of native Docker to ensure Linux filesystem compatibility (for example, `ext4`).

Get the KDB.AI Docker image

To pull the KDB.AI Docker image, you need a bearer token from the KX downloads portal.

Sign in to portal.dl.kx.com.
Click your username in the top right and select Token Management.
Click + Add New Token and copy the generated token.

Tokens have no expiry date but are disabled 90 days after your last interactive login. You can hold a maximum of 3 tokens.

Log in to the KX Docker registry using your portal email and the bearer token:

docker login portal.dl.kx.com -u <your-portal-email> -p <your-bearer-token>

Pull the KDB.AI Docker image:
```
docker pull portal.dl.kx.com/kdbai-db
```

Having trouble pulling the image? Contact support@kdb.ai for assistance.

Start the KDB.AI docker image

Create a location on the local disk to write data:
```
mkdir vdbdata
```
Set permissions to read and write to this directory:
```
chmod 0777 vdbdata
```
Run the container in interactive mode to verify it starts correctly:
KDB_LICENSEKDB_K4LICENSE
Your community license is installed at $HOME/.kx/kc.lic by default as part of the KDB-X install. If you haven't installed it yet, refer to Prerequisites. Generate the base64 value and run the container:
export KDB_LICENSE_B64=$(base64 -w0 $HOME/.kx/kc.lic) docker run -it \ -p 8081:8081 \ -p 8082:8082 \ -e KDB_LICENSE_B64=$KDB_LICENSE_B64 \ -v "$PWD/vdbdata":/tmp/kx/data \ portal.dl.kx.com/kdbai-db
The K4 license is a commercial license distributed by KX's license administration service. If you are a commercial license user upgrading from KDB.AI Server before version 2.0, you must use a KDB-X K4 license to run this image. For licensing enquiries, contact support@kdb.ai. Once you have your license file, generate the base64 value and run the container:
export KDB_K4LICENSE_B64=$(base64 -w0 k4.lic) docker run -it \ -p 8081:8081 \ -p 8082:8082 \ -e KDB_K4LICENSE_B64=$KDB_K4LICENSE_B64 \ -v "$PWD/vdbdata":/tmp/kx/data \ portal.dl.kx.com/kdbai-db
Confirm the startup logs show no errors, then stop the container with Ctrl+C and re-run with -d instead of -it to start it in detached mode. Use docker ps to verify it is running.

In each -p host:container mapping, the host port (left) can be changed to any available port. The container port (right) must not be changed.

For a full configuration reference and deployment options, refer to the Configuration Guide.

Install the KDB.AI client

Install the latest version of KDB.AI client using pip from PyPI using the following command:
PythonREST
pip install kdbai-client
Ensure curl is installed, for example, `which curl`
KDB.AI supports Python (versions 3.9 to 3.13).

Establish and verify the connection:

PythonREST

import kdbai_client as kdbai
session = kdbai.Session(host='localhost', port=8082, mode='qipc')
database = session.database('default')
print(database.tables)
# expected response should be an empty list [] because you haven't created any tables yet

curl http://localhost:8081/api/v2/ready
# expected response 'OK'

Find your container name

Before exporting logs or stopping the container, get your container name:

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Export the KDB.AI docker logs

If you encounter an issue, export your log file by running:

docker logs <your-container-name> > yourDocker.log 2>&1

Send your log file yourDocker.log to the Support team.

Stop the KDB.AI docker image

Run the following command to stop the container:

docker stop <your-container-name>

Next steps

Go to the Quickstart Guide to set up your table schema and start inserting data.
For Docker Compose, air-gapped deployments, and a full environment variable reference, refer to the Configuration Guide.