Skip to content

KDB.AI Server Setup

This section details the steps to setup KDB.AI Server.

Hardware requirements

KDB.AI Server requires an Intel or AMD CPU that support AVX2 instructions or later:

  • Intel CPUs starting from the Haswell architecture.
  • AMD CPUs starting from the Zen architecture.

KDB.AI Server is currently not supported for users on Apple Macs.

Software requirements

The following steps provide guidance for running the KDB.AI Server under Docker.

  1. A Linux kernel of 4.18.0 or later is required to run the KDB.AI container. Examples of such distros include:

    • CentOS 8 or later
    • Red Hat Enterprise Linux (RHEL) 8 or later
    • Ubuntu 18.04 or later
  2. If you run KDB.AI Server on Windows, we recommend using the Windows Subsystem for Linux (WSL) instead of running it directly on Windows. This way, the volume mounts are from a Linux filesystem (for example, ext4) and avoid any related errors.

  3. If you are running Docker on WSL for the first time, follow these steps:

    • ensure Docker Desktop is installed.
    • with Docker Desktop running, ensure the following settings are configured correctly:

      • Settings > General > Use the WSL 2 based engine: Selected
      • Settings > Resources > WSL Integration >

        • Enable integration with my default WSL distro: Select if using Docker on default WSL distro.
        • Enable integration with additional distros: Select for all WSL distros running Docker. If any issue persists, install Docker directly on the WSL distro (assuming it’s not already installed), following the instructions for the specific Linux OS being used.

System requirements

The KDB.AI Server Standard Edition license is limited to 24 cores. When running the Docker container, if the machine contains more than 24 cores, adjust the Docker run command to include --cpuset-cpus, for example --cpuset-cpus 1-24. See step 3 of Start the KDB.AI docker image for more details.

Sign up

Ensure you have signed up for KDB.AI Server Edition here.

If running a KDB.AI Server version before 1.0.0, you must register for a new KDB.AI Server license here and complete a new installation process. For further details, follow the Upgrade KDB.AI Server instructions.

Having trouble finding the registration email? Try this:

  1. Check your spam folder.
  2. Add to the Safe senders list to prevent your personal or corporate antivirus or email protection software to block the email from being delivered.

Bearer token

Once you receive your registration email, obtain a bearer token by doing the following.

  1. Log into the KX downloads portal.
  2. Once authenticated, navigate to
  3. Click Add New Bearer token.
  4. Click Copy Bearer.

Download the KDB.AI image

Using the credentials provided after you register, you can download the image for the specified version of KDB.AI Server.

  1. Login to the docker registry in the downloads portal:

    export USERNAME=<Signup email address>
    export BEARER=<Copied from KX downloads portal>
    docker login -u $USERNAME -p $BEARER

    Your username is your email address registered with KX, your password is the bearer token.

  2. Pull the kdbai-db image:

    docker pull

Download your KDB.AI license

In your registration email, click Download License. Your license is either a k4.lic or kc.lic file and is needed to access your KDB.AI Server database.


For Windows users, this license needs to be saved within your mounted Linux filesystem to work. It does not work if you save the license in your Windows filesystem.

For example, this command works:

export KDB_LICENSE_B64=$(base64 kc.lic)
This command doens't work:

export KDB_LICENSE_B64=\mnt\c\users\yourname\downloads\kc.lic 

Provide a license

  1. Create the environment variable using the corresponding command depending on the format of your license:


    export KDB_LICENSE_B64=$(base64 path-to/kc.lic)


    export KDB_K4LICENSE_B64=$(base64 path-to/k4.lic)

Start the KDB.AI docker image

  1. Create a location on the local disk to write data, indexes, and logs:

    tree .
    └── vecdb
        ├── data
        └── logs
    3 directories, 0 files
  2. Set permissions to read and write to these directories:

    chmod 0777 vecdb/data vecdb/logs
  3. Run the container in detached mode using the following command:

    docker run -d \
        -p 8082:8082 \
        -e KDB_LICENSE_B64 \
        -e KXI_RT_LOG_PATH=/logs \
        -v $PWD/vecdb/data:/data \
        -v $PWD/vecdb/logs:/logs \

    If you do not see a success message, try removing -d from the above command to view the container logs and any potential errors.

    The first port in the -p line is configurable, but the second port 8082 must not be changed.

    If you attempt to run the Docker container on a machine with more than 24 cores, the execution fails with a cores error. To work around this, add a --cpuset-cpus parameter to the Docker run command, for example --cpuset-cpus 1-24.

  4. Check the KDB.AI container is running:

    docker ps 

    If you see an error message and are running docker using sudo, add the -E flag so enviromental variables like KDB_LICENSE_B64 are picked up. Therefore, the command becomes: -E docker ps.

Install the KDB.AI client

  1. Install the latest version of KDB.AI client using pip from PyPI using the following command:

    pip install kdbai-client

    KDB.AI supports Python versions >= 3.8

    Ensure curl is installed, for example, `which curl` 
  2. Establish and verify the connection with the KDB.AI Server:

    import kdbai_client as kdbai
    session = kdbai.Session(endpoint='http://localhost:8082')
    # expected response []
    curl http://localhost:8082/api/v1/ready
    # expected response 'OK'

Python: The result should be an empty list [] because you haven't created any tables yet.

REST: 'OK' response returned

Export the KDB.AI docker logs

If you encounter an issue, we recommend you export your log file.

  1. To export, run:

    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

If you wish you stop the KDB.AI Server, do the following.

  1. To stop the container, run:

    docker stop <your-container-name>

Next steps

Go to our Quickstart Guide page to set up your table schema and start inserting data.