kozou dev

kozou dev is the local runtime command. It brings up the bundled @kozou/svelte-ui Admin UI and an MCP Streamable HTTP server in a single process group, both wired from your kozou.config.yaml. It is the command behind the kozou service in the scaffolded docker-compose.yml, and the fastest way to see all of Kozou’s emitted surfaces against a real database.

This page is the operator reference for what kozou dev starts, the flags it accepts, and how its ports are configured.

Synopsis

kozou dev [--config <path>] [--adapter <kind>] [--api-port <n>]

With no flags, kozou dev reads ./kozou.config.yaml, starts the Admin UI and the MCP HTTP server, and runs until you stop it with Ctrl-C.

What it starts

kozou dev brings up two services:

1. The Admin UI — the bundled @kozou/svelte-ui application, spawned as a child process. It serves the generated CRUD UI for every table and view in your configured schemas. Default port: 3333.
2. The MCP HTTP server — the Streamable HTTP transport from @kozou/mcp, run in-process. It exposes the same Schema Context tools an AI agent can call. Default port: 3334.

Both services are wired from a single kozou.config.yaml, so they share one database connection and one set of UI hints. Stopping the command (Ctrl-C, or any SIGINT / SIGTERM) tears both down together; if the Admin UI process exits on its own, the MCP server is brought down with it.

By default both services bind to 0.0.0.0 so that docker compose port mapping works out of the box. Kozou v0.1 has no authentication on either surface, so a loud warning is printed when either binds to a non-loopback host. Keep kozou dev inside a trusted boundary (your machine, or a private compose network), or put an auth proxy in front of it.

Flags

Flag	Argument	Description
--config	<path>	Path to kozou.config.yaml. Defaults to ./kozou.config.yaml relative to the current working directory.
--adapter	<kind>	Experimental. Set to api to back the REST layer with the in-house @kozou/api server instead of the default REST adapter. The only accepted value is api; any other value is an error. See The experimental --adapter api flag.
--api-port	<n>	Port for the in-house @kozou/api server. Only meaningful together with --adapter api. Defaults to 3335.

There are no host or per-service port flags on kozou dev itself. The UI and MCP ports and bind hosts come from kozou.config.yaml (see below), not from the command line.

Configuring the ports

The Admin UI and MCP HTTP listeners are configured in kozou.config.yaml under server.ui and server.mcp.http. Each takes a port and a host:

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

The values above are the defaults; you only need to write the keys you want to change. As with the rest of the config, ${VAR} and ${VAR:-default} placeholders are expanded from the process environment at load time. See kozou.config.yaml for the full schema, and kozou mcp for the standalone MCP server and its own transport flags.

The Admin UI is a SvelteKit adapter-node server, which rejects form posts whose Origin does not match the server’s expected origin. By default kozou dev sets that origin to http://localhost:<server.ui.port>. If you serve the UI on a different public URL, set the ORIGIN (or KOZOU_ORIGIN) environment variable so form submissions are accepted.

Example

Point kozou dev at a database and a config file, then open the Admin UI:

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou dev --config ./kozou.config.yaml

With a config like this:

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

server:
  ui:
    port: 3333
  mcp:
    http:
      port: 3334

uiHints:
  path: ./ui-hints.yaml

you get the Admin UI on http://localhost:3333 (with CRUD pages for, say, your products, orders, and authors tables) and the MCP HTTP endpoint on http://localhost:3334. The labels, widgets, and descriptions in the UI come from your DDL plus COMMENT tags such as @widget and @ai — for example, a products.status column whose COMMENT enumerates draft / published / archived renders as a select. See Admin UI for a tour of what gets generated, and Connect MCP for pointing an agent at the HTTP endpoint.

The experimental --adapter api flag

Experimental (v0.2). In Kozou v0.1 the REST surface is served by PostgREST. The v0.2 line adds @kozou/api, an in-house REST layer that generates table CRUD, view reads, and a COMMENT-aware OpenAPI document directly from your Schema Context. It is opt-in and experimental: PostgREST remains the default.

When you pass --adapter api, kozou dev also starts the in-house @kozou/api server before bringing up the Admin UI, and wires the UI to talk to it instead of the default REST adapter. This adds a third listener:

kozou dev --adapter api

This brings up:

• the Admin UI on server.ui.port (default 3333),
• the MCP HTTP server on server.mcp.http.port (default 3334), and
• the in-house @kozou/api server on the --api-port value (default 3335).

The @kozou/api server binds to 127.0.0.1 only — it is reached exclusively by the Admin UI’s server-side fetch, so it is never exposed to the browser or the network. Override its port with --api-port if 3335 is taken:

kozou dev --adapter api --api-port 4000

@kozou/api is an experimental, unpublished workspace package, so --adapter api only works when you run kozou from a source or workspace checkout. A published kozou install does not bundle it and prints a clear error telling you to drop --adapter api (which falls back to the default REST adapter). For the full picture — the generated endpoints, the COMMENT-driven OpenAPI output, and the current limits — see The experimental @kozou/api layer.