Worktree .env (kairos-mcp)

This repository is often used as a git worktree. Dotenv files (.env, .env.dev_simple, etc.) live in the worktree root and are not shared with other worktrees.

Unique ports per worktree (same host)

Copying .env* from main duplicates PORT, METRICS_PORT, and URLs that embed the app port (for example AUTH_CALLBACK_BASE_URL in scripts/env/.env.template). If more than one worktree (or main + a worktree) runs the app, tests, or MCP against localhost on the same machine, each worktree needs its own free port pair so listeners do not collide.

Minimum edits after copy (typical dev profile):

• Set PORT to a free host port (not used by another kairos-mcp checkout or service).
• Set METRICS_PORT to another free port.
• Set AUTH_CALLBACK_BASE_URL (and any other http://localhost:<port> dev URLs that must match the app) to use the same host and PORT as the server you start in this worktree.

dev_simple: deploy-run-env.sh defaults PORT to 4300 and METRICS_PORT to 9490 when unset (see ENV=dev_simple). If another checkout already uses those ports on the same host, override PORT and METRICS_PORT in this worktree’s .env / .env.dev_simple.

Docker / infra: if each worktree runs a full Compose stack on one machine, published ports on shared services (Qdrant, Valkey, Keycloak, etc.) can also conflict; resolving that is separate from app PORT and may require different Compose project names, profiles, or host port overrides — not all of that is driven by .env alone.

Automatic behaviour (no manual step)