kozou.config.yaml

kozou.config.yaml is the one file every Kozou command reads. kozou inspect, kozou mcp, and kozou dev all load it to find your database, decide how records are read and written, locate your UI hints, and pick the ports the Admin UI and MCP server listen on. create-kozou writes a fully-commented copy into the project it scaffolds.

Every field has a default. Kozou is designed to start with nothing but a DATABASE_URL environment variable set — if no config file is present, the loader falls back to that variable for the database connection and fills in every other field from its built-in defaults.

For the commands that consume it, see kozou dev. For the UI hints file it points at, see UI hints.

Synopsis

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

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

uiHints:
  path: ./ui-hints.yaml

Kozou looks for kozou.config.yaml in the current working directory by default. Point any command at a different path with --config:

kozou inspect --config ./config/kozou.config.yaml
kozou dev --config ./config/kozou.config.yaml

Sections

database

The PostgreSQL connection and the schemas Kozou introspects.

Field	Type	Default	Description
url	string	— (required)	PostgreSQL connection string. Required, but if it is omitted from the file the loader fills it from the DATABASE_URL environment variable.
schemas	string array	[public]	The schemas Kozou introspects to build its Schema Context.

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

database.url is the only field with no usable default. If it is absent from both the file and the DATABASE_URL environment variable, the loader rejects the config with an error.

adapter

How Kozou reads and writes record data. The Admin UI never talks to PostgreSQL directly — it goes through a data adapter, which keeps the read/write boundary swappable.

Field	Type	Default	Description
type	postgrest	postgrest	The adapter implementation. In v0.1.1 the only value the config file accepts is postgrest.
url	string	http://postgrest:3000	Base URL of the REST endpoint the adapter calls.

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

In v0.1.1, Kozou reads and writes records through PostgREST, a separate service that exposes your database over REST. The scaffolded docker-compose.yml runs it alongside the database.

The v0.2 line adds an experimental in-house REST layer, @kozou/api, behind the same adapter boundary. You opt into it at run time with the --adapter api flag on kozou dev rather than by changing adapter.type:

kozou dev --adapter api

This is experimental and not part of the stable v0.1.1 surface. See The experimental @kozou/api for what it covers and its current limits.

uiHints

Where to find the UI hints file that refines the emitted Admin UI.

Field	Type	Default	Description
path	string or null	null	Path to a UI hints YAML file. When null, Kozou relies on COMMENT-derived hints only.

uiHints:
  path: ./ui-hints.yaml

UI hints layer on top of the conventions Kozou reads from your COMMENT tags (@ai, @widget, @policy, @example). See UI hints for the file format and how it composes with those tags.

server

Bind hosts and ports for the Admin UI and the MCP server that kozou dev starts.

Field	Type	Default	Description
ui.port	integer	3333	Port for the Admin UI.
ui.host	string	0.0.0.0	Bind host for the Admin UI.
mcp.http.port	integer	3334	Port for the MCP HTTP server.
mcp.http.host	string	0.0.0.0	Bind host for the MCP HTTP server.
mcp.stdio	boolean	false	Whether the MCP server uses the stdio transport.

server:
  ui:
    port: 3333
    host: 0.0.0.0
  mcp:
    http:
      port: 3334
      host: 0.0.0.0
    stdio: false

kozou dev runs the Admin UI on server.ui and the MCP HTTP server on server.mcp.http. The defaults bind 0.0.0.0 so the ports are reachable from outside a container (for example, through the Docker Compose port mapping). On a machine reachable from the network, remember that Kozou v0.1.1 ships no authentication layer of its own — bind to a loopback host or place it behind your own gateway when that matters.

cache

How long the introspected Schema Context is cached before Kozou rebuilds it.

Field	Type	Default	Description
ttlMs	integer	60000	Schema Context cache time-to-live, in milliseconds.

cache:
  ttlMs: 60000

The default 60-second TTL means a schema change (for example, after running a migration) can take up to a minute to appear. Lower ttlMs while iterating on the schema; raise it once it is stable.

Environment-variable expansion

The loader expands placeholders in string values against the process environment at load time, before validation. Two forms are recognized:

Form	Behavior
${VAR}	Replaced with the value of VAR. If VAR is unset, it expands to an empty string.
${VAR:-default}	Replaced with the value of VAR, or default if VAR is unset.

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

With that line, Kozou uses $KOZOU_ADAPTER_URL when it is set, and falls back to http://postgrest:3000 when it is not.

To write a literal $, double it: $$ expands to a single $. So $${VAR} produces the literal text ${VAR} rather than expanding it.

Expansion is single-level by design: a value substituted in from the environment is never re-scanned. A secret that legitimately contains ${...} — for example, a ${ sequence inside a DATABASE_URL password — is preserved verbatim instead of being mistaken for another placeholder.

DATABASE_URL fallback

If database.url is missing or empty in the file, the loader fills it from the DATABASE_URL environment variable. This is what lets the bundled template ship url: ${DATABASE_URL} and lets Kozou run from DATABASE_URL alone with no config file at all:

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

The kozou CLI consumes DATABASE_URL, not KOZOU_DATABASE_URL. Reference ${DATABASE_URL} (or any variable you choose) explicitly from database.url if you prefer to be explicit.

Complete example

A fully-commented config covering every section. Every field shown here matches its default, so you can delete any line you do not need to change.

kozou.config.yaml

#
# Every field has a sensible default; only set what you need to override.
# All ${VAR} and ${VAR:-fallback} placeholders are expanded against the
# process environment at load time. Use $$ for a literal `$`.

database:
  # Connection string. Falls back to the DATABASE_URL env var when omitted.
  url: ${DATABASE_URL}
  # Schemas to introspect when building the Schema Context.
  schemas: [public]

server:
  ui:
    port: 3333        # Admin UI port (kozou dev)
    host: 0.0.0.0     # bind host; 0.0.0.0 is container-reachable
  mcp:
    http:
      port: 3334      # MCP HTTP server port (kozou dev)
      host: 0.0.0.0
    stdio: false      # MCP stdio transport

adapter:
  # v0.1.1 reads/writes records through PostgREST.
  type: postgrest
  # Base URL of the REST endpoint; defaults to the compose service.
  url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}

uiHints:
  # Path to the UI hints file, or null to rely on COMMENT tags only.
  path: ./ui-hints.yaml

cache:
  # Schema Context cache TTL in milliseconds.
  ttlMs: 60000

Applied to a schema with products (a status column moving through draft / published / archived), orders, and an authors / books relation, this config introspects the public schema, serves the resulting Admin UI on http://localhost:3333, exposes MCP over HTTP on http://localhost:3334, and rebuilds its Schema Context at most once every 60 seconds.

Where to next

• kozou dev — the command that reads server, adapter, and cache to run the Admin UI and MCP server.
• UI hints — the file uiHints.path points at.
• The experimental @kozou/api — the in-house REST layer behind kozou dev --adapter api.