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 v0.1.1.

Requirements

Runtime requirements for v0.1.1:

• 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, the REST layer, and a kozou service running kozou dev (the bundled Admin UI plus an MCP HTTP server).

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, PostgREST, and a kozou service that runs kozou dev to host the Admin UI and the MCP HTTP server.
• 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 DATABASE_URL and related values.

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:v0.1.1

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:v0.1.1 inspect --help

The same pattern works for the MCP server:

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

The image bundles the kozou CLI and the Admin UI. PostgREST is not bundled — in the Compose stack it runs 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]

adapter:
  type: postgrest
  url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}

uiHints:
  path: ./ui-hints.yaml

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

REST adapter: v0.1 emits its REST surface through PostgREST (the postgrest adapter shown above). The v0.2 line adds an experimental in-house REST layer, @kozou/api, reachable via kozou dev --adapter api. It is experimental — postgrest remains the default for v0.1.1.

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:v0.1.1 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.