Skip to Content
Getting StartedQuick Start

Quick Start

This guide takes you from zero to a working KalamDB flow:

  1. Run the server
  2. Bootstrap authentication
  3. Create a namespace and table
  4. Execute SQL
  5. Connect from the TypeScript SDK or CLI

Use this path if you want the fastest route into a working local KalamDB setup before moving into the TypeScript SDK, HTTP API, PostgreSQL extension, or production guides.

Prerequisites

Pick the path that matches how you want to run the server:

OptionYou need
1. DockerDocker Engine or Docker Desktop
2. Kalam CLIKalam CLI installed (install.sh or npm) and, for TypeScript starters, Node.js plus a package manager (npm, pnpm, yarn, or bun)
3. GitHub binariescurl or a browser — no Rust toolchain required
4. Build from sourceGit and Rust 1.92+

Option 1: Docker

The fastest way to run KalamDB locally is the published image jamals86/kalamdb:latest. Copy-paste the commands below — they start the server, bootstrap auth, and log you in as the initial DBA user.

BASH
docker run -d --name kalamdb -p 2900:2900 \  -e KALAMDB_SERVER_HOST=0.0.0.0 \  -e KALAMDB_JWT_SECRET="$(openssl rand -base64 32)" \  -e KALAMDB_ALLOW_REMOTE_SETUP=true \  -v kalamdb_data:/data \  jamals86/kalamdb:latest sleep 5curl -sS http://127.0.0.1:2900/v1/api/auth/status curl -sS -X POST http://127.0.0.1:2900/v1/api/auth/setup \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!","root_password":"RootPass123!"}' curl -sS -X POST http://127.0.0.1:2900/v1/api/auth/login \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!"}'

What this does:

  • Starts kalamdb-server with data persisted in the named volume kalamdb_data
  • Generates a JWT signing secret (required when binding to 0.0.0.0)
  • Allows first-time setup from your host machine (KALAMDB_ALLOW_REMOTE_SETUP=true)
  • Creates DBA user admin and returns a JWT when login succeeds

Save the access_token from the login response for the SQL steps below.

Docker note: /v1/api/healthcheck is localhost-only inside the container. From your host, use /v1/api/auth/status (as above) or run docker exec kalamdb wget -qO- http://127.0.0.1:2900/v1/api/healthcheck.

Admin UI: http://127.0.0.1:2900/ui — log in as admin with AdminPass123!.

For Docker Compose (single node or 3-node cluster), volume overrides, and Windows PowerShell examples, see Docker Deployment.

Option 2: Kalam CLI (kalam init + kalam dev)

Use this path when you want a project scaffold (kalam.toml, schema.sql, migrations) and a single command that starts the local server, applies schema, and supervises your app.

Step 1 — Install the CLI

BASH
curl -fsSL https://kalamdb.org/install.sh | sh

Or with npm:

BASH
npm install -g @kalamdb/cli

Verify:

BASH
kalam --versionkalam doctor

Step 2 — Scaffold a project with kalam init

Create a directory and run the interactive wizard:

BASH
mkdir my-app && cd my-appkalam init

The wizard asks for:

  1. Project name — written to [project].name in kalam.toml
  2. Schema mode — choose SQL file (schema.sql)
  3. Language targets — TypeScript and/or Dart for generated SDK types
  4. Template — built-in TypeScript starter (for example simple-live)
  5. Package manager — npm, pnpm, yarn, or bun (TypeScript only)
  6. Server mode — choose local so kalam dev can start kalamdb-server for you
  7. Server URL — defaults to http://localhost:2900 for local mode

Non-interactive equivalent (CI or scripted setup):

BASH
kalam init --yes \  --name my-app \  --languages typescript \  --template simple-live \  --package-manager pnpm \  --server-mode local

kalam init creates at minimum:

File / directoryPurpose
kalam.tomlProject config: environments, schema paths, dev orchestration
schema.sqlYour schema source
kalam/migrations/Migration history
kalam/server/server.tomlLocal server config (includes auth.root_password)
src/generated/kalam.tsGenerated TypeScript types (after first dev run)

Step 3 — Start everything with kalam dev

From the project root:

BASH
kalam dev

On startup, kalam dev:

  1. Resolves the dev environment from kalam.toml (http://localhost:2900 by default)
  2. Starts or reuses a local kalamdb-server — if no binary is installed, the CLI can download the matching release into ~/.kalam/bin (interactive terminals only)
  3. Bootstraps auth — logs in as local root using kalam/server/server.toml and saves credentials to ~/.kalam/
  4. Applies schema — runs the migration pipeline against schema.sql
  5. Regenerates types — refreshes SDK artifacts when configured
  6. Supervises app processes — starts commands from [dev.processes] (for example pnpm dev for TypeScript starters)

To wipe local database files and start over, stop the dev session and run kalam db reset (use --yes when reusing a non-project server or in non-interactive shells), then kalam dev again.

Press Ctrl+C to shut down managed processes cleanly.

Useful flags:

BASH
kalam dev --env dev --namespace app --project-dir .kalam dev --force   # skip draft confirmation prompts on startup

Check project state in another terminal:

BASH
kalam statuscurl http://127.0.0.1:2900/v1/api/auth/status

While kalam dev is running, sign in to the local server with root / kalamdb123:

If port 2900 is already in use, kalam dev reuses that server instead of starting a new one. Use a free port when scaffolding:

BASH
kalam init --yes --name my-app --languages typescript --server-mode local --server-url http://localhost:2933

Full references: Project Init and Local Development.

Option 3: GitHub release binaries

Download prebuilt kalamdb-server and kalam archives from KalamDB Releases . Each release publishes platform archives plus a SHA256SUMS file — verify checksums before extracting.

Choose your platform

The latest release ships these server and CLI archives (version shown dynamically):

PlatformServer archiveCLI archive
Linux x86_64kalamdb-server-<ReleaseValue bare fallback="&lt;version&gt;" />-linux-x86_64.tar.gzkalamcli-<ReleaseValue bare fallback="&lt;version&gt;" />-linux-x86_64.tar.gz
Linux ARM64kalamdb-server-<ReleaseValue bare fallback="&lt;version&gt;" />-linux-aarch64.tar.gzkalamcli-<ReleaseValue bare fallback="&lt;version&gt;" />-linux-aarch64.tar.gz
macOS Apple Siliconkalamdb-server-<ReleaseValue bare fallback="&lt;version&gt;" />-macos-aarch64.tar.gzkalamcli-<ReleaseValue bare fallback="&lt;version&gt;" />-macos-aarch64.tar.gz
Windows x86_64kalamdb-server-<ReleaseValue bare fallback="&lt;version&gt;" />-windows-x86_64.zipkalamcli-<ReleaseValue bare fallback="&lt;version&gt;" />-windows-x86_64.zip

Replace <version> with the bare release tag from GitHub (for example 0.5.3-rc.1). macOS Intel builds are not published — use Docker, Rosetta with a Linux binary, or build from source on Intel Macs.

Release archives contain versioned binary names (not kalamdb-server / kalam). You also need a server.toml config file — the binary does not start without one.

Linux (x86_64) example

bash snippetBASH
# 1. Download both archives and SHA256SUMS from the release page, then verify:sha256sum -c SHA256SUMS --ignore-missing # 2. Extract (creates versioned binary names in the current directory)mkdir -p kalamdb-bin && cd kalamdb-bintar -xzf ../kalamdb-server-0.5.4-rc.1-linux-x86_64.tar.gztar -xzf ../kalamcli-0.5.4-rc.1-linux-x86_64.tar.gz # 3. Optional convenience symlinksln -sf kalamdb-server-0.5.4-rc.1-linux-x86_64 kalamdb-serverln -sf kalamcli-0.5.4-rc.1-linux-x86_64 kalam # 4. Create a minimal local configcat > server.toml <<'EOF'[server]host = "127.0.0.1"port = 2900 [storage]data_path = "./data" [limits] [logging]logs_path = "./logs"log_to_console = true [performance] [auth]jwt_secret = "local-binary-test-secret-32chars-min"root_password = "kalamdb123"EOF # 5. Start the server./kalamdb-server-0.5.4-rc.1-linux-x86_64 server.toml

In another terminal, confirm the server is up and run the CLI:

BASH
curl http://127.0.0.1:2900/v1/api/auth/status./kalamcli-<version>-linux-x86_64 --help   # or ./kalam --help if you created the symlink

macOS (Apple Silicon) example

bash snippetBASH
shasum -a 256 -c SHA256SUMS mkdir -p kalamdb-bin && cd kalamdb-bintar -xzf ../kalamdb-server-0.5.4-rc.1-macos-aarch64.tar.gztar -xzf ../kalamcli-0.5.4-rc.1-macos-aarch64.tar.gzln -sf kalamdb-server-0.5.4-rc.1-macos-aarch64 kalamdb-serverln -sf kalamcli-0.5.4-rc.1-macos-aarch64 kalam cat > server.toml <<'EOF'[server]host = "127.0.0.1"port = 2900 [storage]data_path = "./data" [limits] [logging]logs_path = "./logs"log_to_console = true [performance] [auth]jwt_secret = "local-binary-test-secret-32chars-min"root_password = "kalamdb123"EOF ./kalamdb-server-0.5.4-rc.1-macos-aarch64 server.toml

Windows (x86_64) example

powershell snippetpowershell
Get-FileHash .\kalamdb-server-0.5.4-rc.1-windows-x86_64.zip -Algorithm SHA256Get-FileHash .\kalamcli-0.5.4-rc.1-windows-x86_64.zip -Algorithm SHA256Expand-Archive .\kalamdb-server-0.5.4-rc.1-windows-x86_64.zip -DestinationPath .Expand-Archive .\kalamcli-0.5.4-rc.1-windows-x86_64.zip -DestinationPath .@'[server]host = "127.0.0.1"port = 2900[storage]data_path = "./data"[limits][logging]logs_path = "./logs"log_to_console = true[performance][auth]jwt_secret = "local-binary-test-secret-32chars-min"root_password = "kalamdb123"'@ | Set-Content server.toml.\kalamdb-server-0.5.4-rc.1-windows-x86_64.exe server.toml

Then verify from PowerShell or Command Prompt:

powershell
curl http://127.0.0.1:2900/v1/api/auth/status.\kalamcli-<version>-windows-x86_64.exe --help

More platform notes: GitHub Binaries.

Option 4: Build from source

Clone the repository and run the server with Cargo (requires Rust 1.92+):

BASH
git clone https://github.com/kalamdb/KalamDB.gitcd KalamDB/backendcargo run --release --bin kalamdb-server -- server.example.toml

The example config binds to http://127.0.0.1:2900 by default. Copy and edit server.example.toml if you need different paths or secrets.

To build the CLI as well:

BASH
cd ../clicargo build --release./target/release/kalam --help

Verify Health

After starting the server with any option above:

BASH
curl http://127.0.0.1:2900/v1/api/auth/status

For a native or CLI-managed local server you can also use:

BASH
curl http://127.0.0.1:2900/v1/api/healthcheck

Docker users: the health endpoint is localhost-only from inside the container. Use auth/status from the host, or docker exec kalamdb wget -qO- http://127.0.0.1:2900/v1/api/healthcheck.

Bootstrap Authentication

Check whether the server still needs first-time setup:

BASH
curl http://127.0.0.1:2900/v1/api/auth/status

If it returns "needs_setup": true, initialize root + DBA user:

BASH
curl -X POST http://127.0.0.1:2900/v1/api/auth/setup \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!","root_password":"RootPass123!"}'

If the server is already configured, this endpoint returns conflict; in that case, go directly to login.

Then log in:

BASH
curl -X POST http://127.0.0.1:2900/v1/api/auth/login \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!"}'

Keep the returned access_token for API calls.

Create Namespace And Table

BASH
TOKEN="<ACCESS_TOKEN>" curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer $TOKEN" \  -H 'Content-Type: application/json' \  -d '{"sql":"CREATE NAMESPACE IF NOT EXISTS app;"}' curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer $TOKEN" \  -H 'Content-Type: application/json' \  -d @- <<'JSON'{"sql":"CREATE TABLE app.messages (id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(), sender TEXT NOT NULL, content TEXT NOT NULL, created_at TIMESTAMP DEFAULT NOW()) WITH (TYPE='USER', FLUSH_POLICY='rows:1000,interval:60');"}JSON

Insert And Query

BASH
curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer $TOKEN" \  -H 'Content-Type: application/json' \  -d @- <<'JSON'{"sql":"INSERT INTO app.messages (sender, content) VALUES ('alice', 'Hello KalamDB');"}JSON curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer $TOKEN" \  -H 'Content-Type: application/json' \  -d '{"sql":"SELECT * FROM app.messages ORDER BY created_at DESC LIMIT 10;"}'

Connect With TypeScript SDK (@kalamdb/client)

Install the package first:

BASH
npm install @kalamdb/client

Package reference: @kalamdb/client on npm

TS
import { createClient, Auth } from '@kalamdb/client'; const client = createClient({  url: 'http://127.0.0.1:2900',  authProvider: async () => Auth.jwt('<ACCESS_TOKEN>'),}); const res = await client.query('SELECT * FROM app.messages LIMIT 5');console.log(res.results[0]);

Connect With Kalam CLI

Install the CLI with npm or the curl installer:

BASH
npm install -g @kalamdb/cli # orcurl -fsSL https://kalamdb.org/install.sh | sh

Log in and run a query:

BASH
kalam login --instance local --url http://127.0.0.1:2900 --user admin --passwordkalam -c "SELECT * FROM app.messages ORDER BY created_at DESC LIMIT 5;"kalam doctor

If you want to test the OIDC flow instead of local password login:

BASH
kalam login --instance local --url http://127.0.0.1:2900 --oidckalam login --instance local --url http://127.0.0.1:2900 --oidc --no-browser

Full CLI reference: Kalam CLI — start with Project Init and Local Development

Use KalamDB Skills With Coding Agents

Install the official KalamDB skill for Codex, Claude Code, OpenCode, and Agent Skills-compatible tools:

BASH
npx skills add kalamdb/kalamdb-skills

Choose Your Next Track

Building an app or AI-agent backend in TypeScript

Continue with TypeScript Setup, Authentication, Querying & DML, and Realtime Subscriptions.

Building background workers and agent automation

Continue with Topic Consumers & ACK, Consumer Runtime, and AI Agent Coding Guidelines.

Integrating through PostgreSQL

Continue with PostgreSQL Extension Getting Started, SQL Syntax, and Data Type Conversions.

Hardening for production

Continue with Authentication & Bootstrap, Configuration, Security, and OIDC & Issuer Trust.

Advanced features and integrations

Continue with SQL Reference, Vector Search, Dex, OIDC & Issuer Trust, MinIO (S3-Compatible), Jaeger, and OpenTelemetry (OTEL).

Last updated on
v0.5.3-rc.1 ReleaseAI Agent Coding Guidelines