Docker

The container image runs kabactl server as an unprivileged user. Use it for a headless node on any Docker host.

Image


Base	`debian:bookworm-slim`
Entry point	`tini -- kabactl`, default command `server`
User	`kaba`, UID and GID `10001`
Home	`/home/kaba`
Storage directory	`/home/kaba/.config/kaba`
Ports	`28832` (HTTPS API), `28833` (SOCKS5 proxy)
Platforms	`linux/amd64`, `linux/arm64`

Images are tagged v<version> and latest:

docker pull git.djcas9.com/kaba-labs/kabactl/kabactl:latest

# Or pin a version:
docker pull git.djcas9.com/kaba-labs/kabactl/kabactl:v0.87.5

Run

Everything kabactl stores lives under /home/kaba/.config. Mount a volume there or the node gets a new identity and an empty database every time it starts.

docker volume create kaba-data

docker run -d --name kabactl \
  --restart unless-stopped \
  -v kaba-data:/home/kaba/.config \
  -p 127.0.0.1:28832:28832 \
  -p 127.0.0.1:28833:28833 \
  git.djcas9.com/kaba-labs/kabactl/kabactl:latest

Publishing on 127.0.0.1 keeps the API and proxy reachable only from the host. The cluster does not need published ports: the node reaches its peers with outbound connections.

docker logs -f kabactl
curl -k https://localhost:28832/health

Run commands

The image’s entry point is kabactl, so anything after the image name is a subcommand:

# one-off, against the same volume
docker run --rm -v kaba-data:/home/kaba/.config git.djcas9.com/kaba-labs/kabactl/kabactl:latest doctor

# inside the running container
docker exec kabactl kabactl cluster list
docker exec kabactl kabactl cluster invite --name laptop

To join this node to an existing cluster:

docker exec kabactl kabactl cluster join kaba_invite_…
docker restart kabactl

Compose

services:
  kabactl:
    image: git.djcas9.com/kaba-labs/kabactl/kabactl:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:28832:28832"
      - "127.0.0.1:28833:28833"
    volumes:
      - kaba-data:/home/kaba/.config
    environment:
      KABA_BACKEND: cpu

volumes:
  kaba-data:

Configuration

kabactl writes a default config.toml into the volume on first start. To change it, edit the file in the volume and restart, or bind-mount your own over it:

-v $PWD/config.toml:/home/kaba/.config/kaba/config.toml:ro

With a read-only config, kabactl cannot rewrite the file when a new version adds keys. It logs a warning and continues with the merged values in memory.

Environment variables are passed with -e. See the kabactl environment reference.

GPU

The stock image has no GPU drivers. For inference on a GPU, give the container access to the device with your runtime’s mechanism (for NVIDIA, the NVIDIA Container Toolkit and --gpus all) and use an image built with the matching back end. Without one, set KABA_BACKEND=cpu.

[todo: confirm which published image tags include GPU back ends and document the exact run flags for each.]

The tool sandbox in a container

The sandbox that runs model-driven commands needs an OCI runtime (runsc, youki, crun or runc) and the ability to create containers. The stock image contains none, and nested containers need extra privileges, so a containerized node is best used for the API, proxy, mesh, memory and inference, with sandboxed execution pointed at another device through the policy’s Sandbox target.

Root check

kabactl refuses to run as root, but skips that check when it detects a container. The image runs as UID 10001 anyway. If you override the user to root in an environment the check does not recognise, set KABA_ALLOW_ROOT=1.

Build the image yourself

From the kabactl repository, after make release:

make image          # single-arch, local
make buildx-setup   # once
make image-push     # multi-arch, pushes v<version> and latest

Override REGISTRY, IMAGE_REPO and IMAGE_NAME to publish elsewhere.