For the complete documentation index, see llms.txt. This page is also available as Markdown.

Docker

Run the Kitaru server with Docker, using Compose for one host or the server container against your own Postgres.

The server is one container plus Postgres. Compose runs both on a single host; for anything bigger, run the server container against a managed Postgres and keep the same environment variables.

CLI-managed local deployment

For one local deployment per user, let the CLI own the lifecycle:

kitaru login --local

Requires Docker with the Compose v2 plugin. The CLI runs the version-matched zenmldocker/kitaru-server image with PostgreSQL kept private to the Compose network, stores generated runtime secrets in the Kitaru configuration directory, and opens the selected local URL once healthy (http://localhost:8000 by default). Use kitaru login --local --port 9000 or set KITARU_LOCAL_PORT=9000 to expose it on another loopback port; the flag takes precedence and the selected port is persisted with the deployment. Existing images are reused without an automatic pull; kitaru login --local --upgrade is the explicit upgrade path, and KITARU_LOCAL_IMAGE points source builds at a locally built image. kitaru local logs inspects it; kitaru logout stops it (add --volumes to delete the database).

The rest of this page covers manually managed deployments, which are separate from the CLI-owned one.

Docker Compose

The repository ships a Compose file that builds the server and starts Postgres beside it:

git clone https://github.com/zenml-io/kitaru.git
cd kitaru
docker compose up -d
curl http://localhost:8000/health

The shipped Compose file runs with KITARU_SERVER_AUTH_SCHEME: none, which is fine on your laptop but not for a shared server. For a team deployment, set the auth scheme to local and provide real keys (see below and Authentication).

Configuration

The server is configured entirely through KITARU_SERVER_* environment variables. The ones every deployment should set:

Variable
Meaning

KITARU_SERVER_DB_HOST / DB_PORT / DB_USER / DB_PWD / DB_NAME

Postgres connection, or one KITARU_SERVER_DATABASE_URL instead

KITARU_SERVER_AUTH_SCHEME

none (open, dev only) or local (accounts + API keys)

KITARU_SERVER_JWT_SIGNING_KEY

Secret for login tokens; set a long random value

KITARU_SERVER_SECRET_ENCRYPTION_KEY

Key encrypting stored secrets at rest

KITARU_SERVER_DEFAULT_ACCOUNT_PASSWORD

Bootstrap password for the default account

KITARU_SERVER_SERVER_URL

The externally reachable URL clients use

Operational knobs with sensible defaults; raise or lower them deliberately:

Variable
Default
Meaning

KITARU_SERVER_MAX_BLOB_SIZE_BYTES

100 MiB

Upload cap for trace exports and plugin code

KITARU_SERVER_PAYLOAD_OFFLOAD_THRESHOLD_BYTES

20 KiB

Session/node payload size above which it moves to blob storage

KITARU_SERVER_TASK_HEARTBEAT_TIMEOUT_SECONDS

60

How long a silent worker holds a task before it's requeued

KITARU_SERVER_TASK_RETRY_LIMIT

3

Attempts before a stale task is abandoned

KITARU_SERVER_EVALUATOR_TASK_TIMEOUT_SECONDS

300

Per-evaluator process timeout

KITARU_SERVER_IMPORTER_TASK_TIMEOUT_SECONDS

600

Per-import process timeout

KITARU_SERVER_EVALUATION_PAIR_LIMIT

100

Max (session × evaluator) pairs per batch request

KITARU_SERVER_IDEMPOTENCY_KEY_RETENTION_SECONDS

900

How long a stored response stays replayable for a retried request

KITARU_SERVER_LOG_LEVEL

INFO

Server logging

Database migrations run automatically at startup (KITARU_SERVER_SKIP_DB_MIGRATION=true disables that when you manage migrations yourself).

The published image

For anything beyond a laptop, use the published server image instead of building from source:

Any container runtime works: the server listens on port 8000, runs as a non-root user, and all state lives in Postgres. Put TLS in front with your usual ingress or reverse proxy, and scale horizontally if needed, since the server is stateless between requests. On Kubernetes, use the Helm chart, which wraps this same image with migrations, ingress, and secrets handled.

Workers are deployed separately, in the environments your agents live in. See Workers in production.

First login

Then create accounts and API keys for the team: Authentication & API keys.

Last updated

Was this helpful?