kozou dev

kozou dev is the local runtime command. It brings up the bundled @kozou/svelte-ui Admin UI, an MCP Streamable HTTP server, and Kozou’s in-house @kozou/api REST backend in a single process group, all 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, the MCP HTTP server, and the in-house @kozou/api REST backend, and runs until you stop it with Ctrl-C.

What it starts

By default, kozou dev brings up three listeners:

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.
3. The in-house @kozou/api REST backend — Kozou’s own REST layer, run in-process and bound to 127.0.0.1. The Admin UI’s server-side fetches reach it; it is never exposed to the browser. Default port: 3335. Opt out to an external PostgREST with --adapter postgrest — see Choosing the REST backend.

These 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 them down together; if the Admin UI process exits on its own, the others are 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. The Admin UI and MCP HTTP surfaces have no authentication of their own, 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. (The in-house @kozou/api REST backend can enforce JWT + RLS when you configure auth.)

Flags

Flag	Argument	Description
--config	<path>	Path to kozou.config.yaml. Defaults to ./kozou.config.yaml relative to the current working directory.
--adapter	<kind>	The REST backend for this run: api (the in-house @kozou/api, the default) or postgrest (an external PostgREST, opt-out). Overrides the adapter.type config field. See Choosing the REST backend.
--api-port	<n>	Port for the in-house @kozou/api server. Used when the backend is 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.

Choosing the REST backend

Since v1.0, kozou dev serves REST through the in-house @kozou/api backend by default. It is started in-process before the Admin UI, with the UI wired to talk to it. A default kozou dev therefore brings up three listeners:

• 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 --api-port 4000

The backend is chosen by the adapter.type config field (default api); pass --adapter to override it for a single run. To use an external PostgREST instead — for example, an existing deployment — set --adapter postgrest (or adapter.type: postgrest in the config). In that mode no @kozou/api server is started:

kozou dev --adapter postgrest

For the full picture of the in-house backend — the generated endpoints, the COMMENT-driven OpenAPI output, and its security boundary (loopback by default, optional JWT + RLS) — see The @kozou/api REST layer.