Community Edition Installation on Linux and macOS | Kamiwaza Docs

This is documentation for Kamiwaza 0.7.1, which is no longer actively maintained. For the current GA release, see 1.0.1.

Version: 0.7.1

This guide covers installing Kamiwaza Community Edition on Linux and macOS using the pre-built tarball bundles.

Before you start

macOS (Sequoia 15+)

1) Install Homebrew and core tools

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew update

brew install pyenv pyenv-virtualenv docker cairo gobject-introspection jq cfssl etcd cmake

brew install cockroachdb/tap/cockroach

2) Install Docker Desktop

brew install --cask docker

open -a Docker

# optional if Docker created files as root

sudo chown -R "$(whoami)":staff ~/.docker || true

3) Configure Python 3.10 with pyenv

echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.zshrc

echo 'eval "$(pyenv init -)"' >> ~/.zshrc

echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc

source ~/.zshrc

pyenv install 3.10

pyenv local 3.10

4) Install Node.js 22 with NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

export NVM_DIR="${XDG_CONFIG_HOME:-$HOME/.nvm}"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

nvm install 22

5) Download and install Kamiwaza (tarball)

mkdir -p ~/kamiwaza && cd ~/kamiwaza

# Example for 0.5.1 (replace with the latest available version if needed)

curl -L -O https://github.com/kamiwaza-ai/kamiwaza-community-edition/raw/main/kamiwaza-community-0.5.1-OSX.tar.gz

tar -xvf kamiwaza-community-0.5.1-OSX.tar.gz

bash install.sh --community

Linux (Ubuntu 22.04 and 24.04 LTS)

1) [For Ubuntu 24.04 only] Install Python 3.10

Kamiwaza CE requires Python 3.10. These commands will install Python 3.10 on Ubuntu 24.04.

sudo apt update

sudo apt install software-properties-common -y

sudo add-apt-repository ppa:deadsnakes/ppa

sudo apt update && sudo apt upgrade -y

sudo apt install -y python3.10

sudo ln -sf /usr/bin/python3.10 /usr/local/bin/python

2) System update and core packages

sudo apt update && sudo apt upgrade -y

sudo apt install -y python3.10 python3.10-dev libpython3.10-dev python3.10-venv golang-cfssl python-is-python3 etcd-client net-tools curl jq libcairo2-dev libgirepository1.0-dev

3) Node.js 22 with NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

export NVM_DIR="${XDG_CONFIG_HOME:-$HOME/.nvm}"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

nvm install 22

4) Docker Engine + Compose v2

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io

sudo mkdir -p /usr/local/lib/docker/cli-plugins

sudo curl -SL "https://github.com/docker/compose/releases/download/v2.39.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/lib/docker/cli-plugins/docker-compose

sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose

sudo usermod -aG docker $USER

sudo chown $USER:$USER /var/run/docker.sock

# Log out and back in (or reboot) so the docker group membership takes effect

5) Install CockroachDB and additional dependencies

wget -qO- https://binaries.cockroachdb.com/cockroach-v23.2.12.linux-amd64.tgz | tar xvz

sudo cp cockroach-v23.2.12.linux-amd64/cockroach /usr/local/bin

sudo apt install -y libcairo2-dev libgirepository1.0-dev

6) (Optional) NVIDIA GPU support

Use this section if all of the following are true:

If you are installing on an Ubuntu 22.04 or 24.04 instance with an NVIDIA GPU where nvidia-smi doesn't work, you likely need to do this. However, many cloud-provided images come with NVIDIA drivers pre-installed.

Install the recommended NVIDIA driver, then the NVIDIA Container Toolkit, and configure Docker:

# 1) Install the recommended NVIDIA driver

## If 'ubuntu-drivers' is missing, install it first:

##   sudo apt update && sudo apt install -y ubuntu-drivers-common

sudo apt update

sudo ubuntu-drivers autoinstall

Perform system reboot:

sudo reboot

After the reboot, install the container toolkit and configure Docker:

# 2) Install NVIDIA Container Toolkit repository and package

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list > /dev/null

sudo apt update

sudo apt install -y nvidia-container-toolkit

# 3) Configure Docker to use the NVIDIA runtime and restart Docker

sudo nvidia-ctk runtime configure --runtime=docker

sudo systemctl restart docker

# 4) Test GPU access from Docker (should print nvidia-smi output and exit)
docker run --rm --gpus all nvidia/cuda:12.4.1-runtime-ubuntu22.04 nvidia-smi

Verify the driver is installed with:

nvidia-smi

7) Download and install Kamiwaza (tarball)

mkdir -p ~/kamiwaza && cd ~/kamiwaza

# Example for 0.5.1 (replace with the latest available version if needed)

wget https://github.com/kamiwaza-ai/kamiwaza-community-edition/raw/main/kamiwaza-community-0.5.1-UbuntuLinux.tar.gz

tar -xvf kamiwaza-community-0.5.1-UbuntuLinux.tar.gz

bash install.sh --community

Start the platform

After installation completes:

# Community Edition

bash startup/kamiwazad.sh start

Access the web console at https://localhost

Troubleshooting

Notes