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 over that loopback — and so can anything else sharing it. 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.

Both the Admin UI and the MCP HTTP server bind 127.0.0.1 by default, so neither is reachable from another machine out of the box. The shipped docker-compose.yml sets KOZOU_UI_HOST / KOZOU_MCP_HTTP_HOST to 0.0.0.0 inside the container — a container’s loopback is its own, so the port mapping could not otherwise reach the listeners — and publishes both ports on the host’s 127.0.0.1 only. Those two 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.)

Running without the MCP endpoint

If no agent will ever connect, kozou dev can leave the MCP HTTP endpoint out entirely — see server.mcp.http.enabled for the setting and everything it turns off.

What is specific to this command: kozou dev then starts no MCP listener and no schema cache (that cache exists here only to serve MCP), and names on startup which surfaces are still up rather than leaving you to guess:

[kozou dev] mcp HTTP endpoint disabled (server.mcp.http.enabled / KOZOU_MCP_HTTP_ENABLED); serving the Admin UI and REST only

The Admin UI and the REST backend are untouched, so both still introspect the database as usual. On the external-REST opt-out (--adapter postgrest) the same line reads serving the Admin UI only, because this command names what it is actually running.

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, and the MCP endpoint additionally takes enabled:

server:
  ui:
    port: 3333
    host: 127.0.0.1
  mcp:
    http:
      port: 3334
      host: 127.0.0.1
      enabled: true

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. The bind hosts, the MCP enabled flag and the MCP advertisedUrl can also be set directly as KOZOU_UI_HOST, KOZOU_MCP_HTTP_HOST, KOZOU_MCP_HTTP_ENABLED and KOZOU_MCP_HTTP_ADVERTISED_URL, which — unlike ${VAR} expansion — apply even when there is no config file at all; see Environment overrides. 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, so nothing on another machine can reach it. It is not private, though: the Admin UI reaches it over that loopback, and so can anything else sharing the loopback — your own browser at http://127.0.0.1:3335, another process on your machine, another process in the container under compose. It carries no authentication until you configure auth. 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.