Installation

Kozou ships through three channels: a published Docker runtime image on GHCR, a set of npm packages (CLI and libraries), and a project scaffold that wires them together with Docker Compose. This page covers each path. If you just want the fastest route to a running stack, start with option A, then read Quickstart.

The current published release is v1.15.1.

Requirements

Runtime requirements:

• PostgreSQL 16 or later — the canonical source of truth that Kozou reads from.
• Docker 24 or later (optional) — recommended for the docker compose up stack and required if you want to pull the runtime image directly.
• Node.js 20 or later — for running the npm-published packages directly (for example, npx kozou …).

Contributors additionally need pnpm 9 or later to build the monorepo. See Contributing for the development environment setup.

Option A — Scaffold + Docker Compose

This is the simplest path. The create-kozou scaffold writes a project directory wired for Docker Compose, so a single docker compose up brings the full stack online: PostgreSQL and a kozou service running kozou dev — the bundled Admin UI, an MCP HTTP server, and Kozou’s in-house REST backend, all served in-process. No separate REST container is part of the default stack.

create-kozou ships as a secondary bin of the kozou package rather than a standalone npm package, so npx needs -p kozou to find it on a clean machine.

# Scaffold a project.
npx -p kozou create-kozou my-project
cd my-project

# Copy the env template, then bring up the full stack.
cp .env.example .env
docker compose up

The scaffold generates:

• docker-compose.yml — brings up PostgreSQL and a kozou service that runs kozou dev to host the Admin UI, the MCP HTTP server, and the in-house REST backend (all in-process). An external PostgREST is included only as a commented-out opt-out service.
• kozou.config.yaml — the configuration file that drives every Kozou command.
• ui-hints.yaml — UI hints referenced from kozou.config.yaml.
• .env.example — a template you copy to .env to supply the database credentials (POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB) and other stack settings. docker compose up builds the DATABASE_URL from these, so there is no connection string to wire by hand.

A starter migration is included too, so the database comes up with a schema to introspect.

By default the Admin UI listens on port 3333 and the MCP HTTP server on 3334; you can override these via server.ui and server.mcp.http in kozou.config.yaml.

Option B — The GHCR runtime image

The CLI runtime is published to GitHub Container Registry as a multi-arch manifest, native on both linux/amd64 and linux/arm64. Pull it directly when you want to run the kozou CLI without installing Node.js locally:

docker pull ghcr.io/kozou-dev/kozou:latest

For a reproducible deployment, pin a release tag (for example the current release shown above, ghcr.io/kozou-dev/kozou:vX.Y.Z) instead of :latest — every release is tagged on GitHub and GHCR.

Run any subcommand by appending it to docker run. For example, to see the flags for inspect:

docker run --rm ghcr.io/kozou-dev/kozou:latest inspect --help

The same pattern works for the MCP server:

docker run --rm ghcr.io/kozou-dev/kozou:latest mcp --help

The image bundles the kozou CLI, the Admin UI, and the in-house REST backend. PostgREST is not bundled and is not part of the default stack — it is an optional opt-out you can add as a side-by-side container.

Option C — The npm CLI

Install the CLI globally to put its bin entries on your $PATH:

npm install -g kozou

This exposes two bins:

• kozou — the main multi-command CLI (inspect / mcp / dev).
• create-kozou — scaffolds a project directory (the generator used in option A).

To run the CLI without a global install, use npx:

npx kozou inspect --help

The CLI needs a reachable PostgreSQL and a kozou.config.yaml. The bundled config template reads the connection string from the DATABASE_URL environment variable through a ${DATABASE_URL} placeholder, so set it when you invoke a command:

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou inspect --format yaml > schema.yaml

kozou inspect introspects the configured database and emits a Schema Context to stdout (or to --output <path>). kozou mcp --stdio starts an MCP server over stdio; kozou mcp --http serves the same tools over HTTP (--port / --host configure the listener, and stdio stays the default). kozou dev runs the Admin UI alongside an MCP HTTP server, both wired up from kozou.config.yaml.

A minimal kozou.config.yaml looks like this:

database:
  url: ${DATABASE_URL}
  schemas: [public]

uiHints:
  path: ./ui-hints.yaml

${VAR} and ${VAR:-default} are expanded from the process environment when the config loads.

REST adapter: @kozou/api, Kozou’s in-house REST layer, is the default backend since v1.0 — kozou dev serves it in-process, with no separate container and no adapter section required, and its REST wire format and OpenAPI document are a stable contract. To opt out to an external PostgREST instead, add an adapter block (type: postgrest, url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}) or pass kozou dev --adapter postgrest.

Option D — Library packages for embedding

If you are building a custom host or embedding the MCP server into your own application, install the workspace packages from npm:

npm install kozou @kozou/core @kozou/introspect @kozou/mcp @kozou/svelte-ui

These give you the introspection engine (@kozou/introspect), the core compiler (@kozou/core), the MCP server (@kozou/mcp), and the reference Admin UI components (@kozou/svelte-ui), with the kozou CLI alongside them.

Verifying the install

Confirm the CLI resolves and prints its command surface:

kozou inspect --help

If you pulled the runtime image instead, run the equivalent through Docker:

docker run --rm ghcr.io/kozou-dev/kozou:latest inspect --help

Either should print the flags for inspect without error. From here, point the CLI at a database to produce real output — a products table with a status column (draft / published / archived) or an orders relation makes a good first target.

Next steps

• Getting started — the concepts behind Kozou and how the pieces fit together.
• Quickstart — go from an empty directory to a running Admin UI and live MCP context.