Requirements

What you need on your machine to develop with Kumiko.

Runtime

Tool	Version	Why
Bun	≥ 1.2	runtime, package manager, test runner, bundler
Node.js	≥ 20	optional, Astro/docs site builds only
Docker	any recent	local PostgreSQL + Redis containers

Bun handles server execution, tests, and CLI. Node is only needed when building the docs/marketing Astro sites.

Services (run via `bun run dev`, the scaffolded app’s `bin/dev.ts`)

Service	Port	Why
PostgreSQL 18	15432	primary store (event store + projections)
Redis 7	16379	SSE pub/sub + rate limiting + caching
Meilisearch	optional	full-text search backend (when used)

High ports avoid conflicts with system installs of the same services.

Production

Same Bun version in production. The server bundle is self-contained except for native externals that stay as runtime deps:

@node-rs/argon2, bullmq, postgres, ioredis, temporal-polyfill

Pinned via the workspace package.json files (bullmq/ioredis/postgres/ temporal-polyfill in packages/framework/package.json, @node-rs/argon2 in packages/bundled-features/package.json), production image runs bun install --production against the generated server bundle.

Optional

GitHub CLI (gh), for PR/issue work from the command line
Pulumi, only if you deploy to K3s yourself (the K3s deploy guide covers it)

What you DON’T need

npm, pnpm, or Yarn, Bun only (bun.lock)
Global TypeScript / Vite installs, all workspace-local
Global schema/ORM tools, schema is managed per-app via kumiko schema

Common gotchas

The service ports are deliberately high. bun run dev talks to PostgreSQL on 15432 and Redis on 16379, not 5432 / 6379, a system-wide install of either keeps running next to it, and a connection string copied from elsewhere points at the wrong instance.
Node is not a runtime dependency. It only builds the Astro sites; the app itself never runs on it, so a Node version mismatch is not the cause of a server that won’t boot.
Native externals are not bundled. @node-rs/argon2, bullmq, postgres, ioredis and temporal-polyfill stay runtime deps; the production image installs them next to the server bundle via bun install --production.