Add Podman local runtime support

.agents/skills/kitaru-dev/SKILL.md

@@ -74,7 +74,7 @@ Agent-facing commands use the version-1 structured contract. Success documents i
 
 For agent-facing use, prefer `--output json --machine --non-interactive --no-browser`. A deliberate dashboard or device-login handoff is the exception.
 
-Document login consistently: `kitaru login` starts the interactive managed-cloud device flow and connects to the Kitaru workspace selected or created in the browser. `kitaru login SERVER` targets the full managed or self-hosted instance URL, while `kitaru login --local` provisions or reuses the CLI-owned Docker Compose deployment. The local deployment defaults to `http://localhost:8000`; `--port` takes precedence over `KITARU_LOCAL_PORT`, and the selected port persists with the deployment. `kitaru logout` stops that deployment when it is selected, and `kitaru logout --volumes` also deletes its PostgreSQL data.
+Document login consistently: `kitaru login` starts the interactive managed-cloud device flow and connects to the Kitaru workspace selected or created in the browser. `kitaru login SERVER` targets the full managed or self-hosted instance URL, while `kitaru login --local` provisions or reuses the CLI-owned Docker or Podman Compose deployment. The local deployment defaults to `http://localhost:8000`; `--port` takes precedence over `KITARU_LOCAL_PORT`, and the selected port persists with the deployment. `kitaru logout` stops that deployment when it is selected, and `kitaru logout --volumes` also deletes its PostgreSQL data.
 
 `kitaru status` shows the selected server, provenance, credential state, compatibility, and live-worker count. `kitaru info` adds local package, Python, platform, and server details. `kitaru doctor` runs independent local, server, authentication, and tooling checks without stopping after the first failure. These commands never print secret values.
 

.claude/skills/kitaru-dev/SKILL.md

@@ -74,7 +74,7 @@ Agent-facing commands use the version-1 structured contract. Success documents i
 
 For agent-facing use, prefer `--output json --machine --non-interactive --no-browser`. A deliberate dashboard or device-login handoff is the exception.
 
-Document login consistently: `kitaru login` starts the interactive managed-cloud device flow and connects to the Kitaru workspace selected or created in the browser. `kitaru login SERVER` targets the full managed or self-hosted instance URL, while `kitaru login --local` provisions or reuses the CLI-owned Docker Compose deployment. The local deployment defaults to `http://localhost:8000`; `--port` takes precedence over `KITARU_LOCAL_PORT`, and the selected port persists with the deployment. `kitaru logout` stops that deployment when it is selected, and `kitaru logout --volumes` also deletes its PostgreSQL data.
+Document login consistently: `kitaru login` starts the interactive managed-cloud device flow and connects to the Kitaru workspace selected or created in the browser. `kitaru login SERVER` targets the full managed or self-hosted instance URL, while `kitaru login --local` provisions or reuses the CLI-owned Docker or Podman Compose deployment. The local deployment defaults to `http://localhost:8000`; `--port` takes precedence over `KITARU_LOCAL_PORT`, and the selected port persists with the deployment. `kitaru logout` stops that deployment when it is selected, and `kitaru logout --volumes` also deletes its PostgreSQL data.
 
 `kitaru status` shows the selected server, provenance, credential state, compatibility, and live-worker count. `kitaru info` adds local package, Python, platform, and server details. `kitaru doctor` runs independent local, server, authentication, and tooling checks without stopping after the first failure. These commands never print secret values.
 

README.md

@@ -44,7 +44,7 @@ Kitaru turns that history into something you can test:
 
 ## ⚡ Get started
 
-**1. Install.** Open a terminal in your agent's repository and run one line. It adds Kitaru to that project's environment with `uv` (the worker that replays your agent has to live next to its dependencies), installs the coding-agent skills, and registers the MCP server with Claude Code, Codex, Cursor, and Windsurf (that part is `kitaru setup`, re-run it after installing a new editor). It ends by printing the two ways to get a server: `kitaru login --local` (Docker, free) or `kitaru login` for the managed cloud (14-day trial, no credit card required).
+**1. Install.** Open a terminal in your agent's repository and run one line. It adds Kitaru to that project's environment with `uv` (the worker that replays your agent has to live next to its dependencies), installs the coding-agent skills, and registers the MCP server with Claude Code, Codex, Cursor, and Windsurf (that part is `kitaru setup`, re-run it after installing a new editor). It ends by printing the two ways to get a server: `kitaru login --local` (Docker or Podman, free) or `kitaru login` for the managed cloud (14-day trial, no credit card required).
 
 ```bash
 curl -fsSL https://kitaru.ai/install | bash
@@ -56,12 +56,12 @@ Already in Claude Code, Codex, or Cursor? Open the repository there and paste th
 Set up Kitaru in this repository by following https://kitaru.ai/install.md. Use the one-line installer and tell me what it did.
 ```
 
-Prefer to do it by hand? Add Kitaru to your project's environment, then choose managed cloud with `uv run kitaru login`, or provision the local FastAPI + Postgres server with Docker:
+Prefer to do it by hand? Add Kitaru to your project's environment, then choose managed cloud with `uv run kitaru login`, or provision the local FastAPI + Postgres server with Docker or Podman:
 
 ```bash
 uv add "kitaru[cli,worker,mcp]" kitaru-pydantic-ai    # or: pip install
 uv run kitaru login                                   # managed cloud; 14-day trial, no credit card required
-uv run kitaru login --local                           # local server in Docker
+uv run kitaru login --local                           # local server in Docker or Podman
 # or: uv run kitaru login <your-team-url>
 ```
 

changelog.d/podman-local-login.added.md

@@ -0,0 +1 @@
+- Added Podman support for CLI-managed local deployments created with `kitaru login --local`.

docs/CLAUDE.md

@@ -143,6 +143,6 @@ this FumaDocs reference app, and generated output).
 
 - Treat `KITARU_*` environment variables as the public configuration surface in docs and examples. Mention `ZENML_*` only as a compatibility note when needed.
 - Agent-facing CLI docs should describe the version-1 structured contract: success documents include `schema_version`, `command`, `ok`, `warnings`, `links`, and `next_actions`, plus `item` or `items`, `count`, and `page`; streaming commands emit JSONL events.
-- Login docs/guidance should treat `kitaru login SERVER` as managed or self-hosted login and `kitaru login --local` as provisioning or reusing the CLI-owned Docker Compose deployment. The local deployment defaults to `http://localhost:8000`; `--port` takes precedence over `KITARU_LOCAL_PORT`, and the selected port persists with the deployment.
+- Login docs/guidance should treat `kitaru login SERVER` as managed or self-hosted login and `kitaru login --local` as provisioning or reusing the CLI-owned Docker or Podman Compose deployment. The local deployment defaults to `http://localhost:8000`; `--port` takes precedence over `KITARU_LOCAL_PORT`, and the selected port persists with the deployment.
 - Treat `src/kitaru/cli/app.py`, the offline `kitaru schema` output, and the generated OpenAPI document as the command and API authorities. Do not document v1 runtime commands such as `kitaru init`, `kitaru stack`, `kitaru model`, or `kitaru executions` unless they are reintroduced in v2 source and tests.
 - Native MCP documentation must match `tests/mcp/snapshots/metrics.json` and `src/kitaru/mcp/registry.py`. Do not copy tool counts into prose; run `just mcp-schema-check` and describe the tools present in the current snapshot. The native v2 MCP server does not expose stack or model-alias management.

docs/book/deploy/docker.md

@@ -15,7 +15,7 @@ For one local deployment per user, let the CLI own the lifecycle:
 kitaru login --local
 ```
 
-Requires [Docker](https://docs.docker.com/get-started/get-docker/) with the [Compose v2 plugin](https://docs.docker.com/compose/install/). The CLI runs the version-matched `zenmldocker/kitaru-server` image with PostgreSQL kept private to the Compose network, stores generated runtime secrets in the Kitaru configuration directory, and opens the selected local URL once healthy (`http://localhost:8000` by default). Use `kitaru login --local --port 9000` or set `KITARU_LOCAL_PORT=9000` to expose it on another loopback port; the flag takes precedence and the selected port is persisted with the deployment. Existing images are reused without an automatic pull; `kitaru login --local --upgrade` is the explicit upgrade path, and `KITARU_LOCAL_IMAGE` points source builds at a locally built image. `kitaru local logs` inspects it; `kitaru logout` stops it (add `--volumes` to delete the database).
+Requires [Docker](https://docs.docker.com/get-started/get-docker/) with the [Compose v2 plugin](https://docs.docker.com/compose/install/), or [Podman](https://podman.io/docs/installation) with Compose support. The CLI runs the version-matched `zenmldocker/kitaru-server` image with PostgreSQL kept private to the Compose network, stores generated runtime secrets in the Kitaru configuration directory, and opens the selected local URL once healthy (`http://localhost:8000` by default). Use `kitaru login --local --port 9000` or set `KITARU_LOCAL_PORT=9000` to expose it on another loopback port; the flag takes precedence and the selected port is persisted with the deployment. Existing images are reused without an automatic pull; `kitaru login --local --upgrade` is the explicit upgrade path, and `KITARU_LOCAL_IMAGE` points source builds at a locally built image. `kitaru local logs` inspects it; `kitaru logout` stops it (add `--volumes` to delete the database).
 
 The rest of this page covers manually managed deployments, which are separate from the CLI-owned one.
 

docs/book/getting-started/installation.md

@@ -19,7 +19,7 @@ That one command:
 4. Prints the two ways to get a server, and stops:
 
 ```
-uv run kitaru login --local    local, in Docker. Free, open source.
+uv run kitaru login --local    local, with Docker or Podman. Free, open source.
 uv run kitaru login            managed cloud. 14-day trial, no credit card required.
 ```
 
@@ -48,7 +48,7 @@ Works on macOS, Linux, WSL, and Git Bash on Windows. Running it again upgrades.
 uv add "kitaru[cli,mcp,worker]" kitaru-pydantic-ai    # into this project; pick your adapter
 uv run kitaru setup                                   # skills + MCP server for every coding agent found
 uv run kitaru login                                   # managed cloud; 14-day trial, no credit card required
-uv run kitaru login --local                           # local server in Docker
+uv run kitaru login --local                           # local server in Docker or Podman
 # or: uv run kitaru login <team-url>                  # an existing managed or self-hosted workspace
 ```
 
@@ -66,13 +66,13 @@ Set up Kitaru in this repository by following https://kitaru.ai/install.md. Use
 kitaru doctor        # or: uvx kitaru doctor, before you open a new terminal
 ```
 
-It checks the CLI, the server connection, authentication, and whether the skills are installed (`kitaru setup` installs them if not). Server connection and authentication fail until you have run `kitaru login --local` (needs [Docker](https://docs.docker.com/get-started/get-docker/)) or `kitaru login` for the managed cloud; the sections below cover both.
+It checks the CLI, the server connection, authentication, and whether the skills are installed (`kitaru setup` installs them if not). Server connection and authentication fail until you have run `kitaru login --local` (see [The local server](#the-local-server)) or `kitaru login` for the managed cloud; the sections below cover both.
 
 Then read the [Quickstart](quickstart.md). It is written as prompts for your coding agent, and everything it needs is now in place.
 
 ## The local server
 
-The server is FastAPI + Postgres, and the CLI can run both for you. All it needs is [Docker](https://docs.docker.com/get-started/get-docker/) with the [Compose v2 plugin](https://docs.docker.com/compose/install/):
+The server is FastAPI + Postgres, and the CLI can run both for you. Install [Docker](https://docs.docker.com/get-started/get-docker/) with the [Compose v2 plugin](https://docs.docker.com/compose/install/), or [Podman](https://podman.io/docs/installation) with Compose support:
 
 ```bash
 kitaru login --local
@@ -86,7 +86,7 @@ kitaru logout                # stop the containers; the database persists
 kitaru logout --volumes      # stop and delete the database (a clean reset)
 ```
 
-After upgrading the `kitaru` package, upgrade the local server to match with `kitaru login --local --upgrade`; a plain login deliberately never replaces the server image. Prefer to manage Docker yourself, or need a shared deployment with your own Postgres, real auth, and TLS? See [Docker](../deploy/docker.md) and [Deploy Kitaru](../deploy/README.md).
+After upgrading the `kitaru` package, upgrade the local server to match with `kitaru login --local --upgrade`; a plain login deliberately never replaces the server image. Prefer to manage the containers yourself, or need a shared deployment with your own Postgres, real auth, and TLS? See [Docker](../deploy/docker.md) and [Deploy Kitaru](../deploy/README.md).
 
 ## Connect to managed cloud or a team server
 

docs/book/guides/post-import-insights.md

@@ -11,7 +11,7 @@ The independently versioned `kitaru-post-import-insights` package supplies two a
 
 ## Set up a worker and import
 
-Start with a connected Kitaru installation and a registered agent. See [Installation](../getting-started/installation.md) for a local Docker server or an existing team server, and [Importing sessions](importing-sessions.md) for the trace format and agent setup. Keep the server and worker on the same Kitaru version.
+Start with a connected Kitaru installation and a registered agent. See [Installation](../getting-started/installation.md) for a local server or an existing team server, and [Importing sessions](importing-sessions.md) for the trace format and agent setup. Keep the server and worker on the same Kitaru version.
 
 In a project environment, install the CLI and worker and connect locally:
 

examples/python/pydantic_ai_ticket_resolver/README.md

@@ -16,7 +16,7 @@ Want to see the complete Kitaru loop without setting anything up first? [Watch t
 
 - [Git](https://git-scm.com/)
 - [uv](https://docs.astral.sh/uv/)
-- Docker, only if you use the optional local Kitaru server
+- Docker or Podman, only if you use the optional local Kitaru server
 - Node.js and `npx`, for installing the optional coding-agent skills
 
 No model-provider or Langfuse credentials are needed for the checked-in import.
@@ -50,7 +50,7 @@ uv run kitaru session list \
 
 If the agent and its ten imported sessions already exist, skip to [Continue with a coding agent](#continue-with-a-coding-agent). The guided tour will inspect and resume that state before it creates anything. If neither exists, continue with the registration below. If only part of the setup exists, or `returns-resolver` belongs to another project, select a different server so the fixed example names do not collide.
 
-If no usable server is selected and you want an isolated local server for the example, start and select one with Docker:
+If no usable server is selected and you want an isolated local server for the example, start and select one with Docker or Podman:
 
 ```bash
 uv run kitaru login --local

install.sh

@@ -21,7 +21,7 @@
 #      found (printing the JSON for everything else). Re-run `kitaru setup`
 #      after installing a new coding agent. Kitaru releases before `setup`
 #      existed get the same steps done by this script instead.
-#   4. Stops there and prints the two ways to get a server: local in Docker
+#   4. Stops there and prints the two ways to get a server: local in Docker or Podman
 #      (`kitaru login --local`) or the managed cloud (`kitaru login`). Login
 #      is a decision, so the script does not make it for you.
 #
@@ -479,7 +479,7 @@ if [ -n "$KITARU_SERVER" ]; then
 else
   say "  Next, pick where your Kitaru server lives:"
   say ""
-  say "    ${C_BOLD}$K login --local${C_RESET}    local, in Docker. Free, open source."
+  say "    ${C_BOLD}$K login --local${C_RESET}    local, with Docker or Podman. Free, open source."
   say "    ${C_BOLD}$K login${C_RESET}            managed cloud. 14-day trial, no credit card required."
 fi
 say ""

src/kitaru/cli/app.py

@@ -667,7 +667,7 @@ def _add_parameter_help(function: F, spec: CommandSpec) -> None:
                 "boolean",
                 "option",
                 False,
-                "Provision and use a local Docker deployment.",
+                "Provision and use a local container deployment.",
             ),
             ParameterSpec(
                 "--port",
@@ -856,7 +856,7 @@ async def local_logs(
     tail: int = 100,
     follow: bool = False,
 ) -> CommandResult:
-    """Read or follow logs from the local Docker Compose deployment."""
+    """Read or follow logs from the local container deployment."""
     if follow and get_output_context().mode == "json":
         raise CLIError(
             "invalid_arguments",