.env.template

# AUTO-GENERATED from .env.schema. Do NOT edit by hand.
# Run `pnpm run env:generate --apply` after editing the schema.
#
# This is the 1Password injection template — the single source of truth
# for dev environment values. Materialize your local .env with:
#
#   pnpm run env:pull           # = op inject -i .env.template -o .env
#
# Secrets are pulled from the "Kodus-Dev" vault in 1Password (each item
# is named after its env var; the value lives in the "password" field).
# Non-secret defaults live inline here — edit the schema to change them.
#
# First-time setup: scripts/env/README.md (section: Pulling values from 1Password)


# ============================================================
# Environment
# ============================================================

# Runtime mode. In the kodus-ai dev tree this stays `development`
# (verbose logs, host-only auth cookies, dev-seed endpoints enabled).
# For self-hosted the installer ships `production` because every
# self-hosted deployment IS a production environment: with
# `development` the SSO handoff cookie is emitted without a Domain
# attribute and without the Secure flag (auth.controller.ts:287,292 +
# derive-sso-cookie-domain.ts:33), so the browser stores it host-only
# on the API origin and the front-end on a different subdomain can't
# read it — hard regression for any customer using SSO. Cloud envs
# are templated by infra-as-code, not this file.
# (type: enum(development,production,test))
API_NODE_ENV=development

# Database environment selector — affects SSL defaults.
# (type: enum(development,production,test))
API_DATABASE_ENV=development

# Disable SSL on ALL Postgres connections (default + analytics warehouse).
# Local docker dev and self-hosted both run a Postgres container with no
# SSL, so the default is true. Cloud (AWS RDS, etc) requires SSL — its
# deploy env MUST set this to false explicitly.
# Covers ALL data sources — individual API_PG_DB_SSL only flipped the
# primary connection, which is why the api still crashed on the analytics
# connection (db_postgres is non-loopback, so SSL stayed on) in the past.
# (type: boolean)
API_DATABASE_DISABLE_SSL=true

# Log verbosity. Cloud runs at info; self-hosted defaults to error to keep
# disk usage and noise low for users without log aggregation.
# (type: enum(error,warn,info,debug))
API_LOG_LEVEL=info

# Pretty-print logs (dev) vs JSON (prod).
# (type: boolean)
API_LOG_PRETTY=true

# Cloud-only — billing + analytics. Self-hosted MUST keep false.
# (type: boolean)
API_CLOUD_MODE=true

# Released version tag, set by CI on prod builds.
RELEASE_VERSION=local

# Dev-only bypass of permission validation. Cloud devs only.
# (type: boolean)
API_DEVELOPMENT_MODE=false

# Dev-only override for the global Kody Rules import tier so the
# free/trial/paid UI can be exercised locally (where an install usually has no
# license and would otherwise resolve to `free`). Only honored when
# API_DEVELOPMENT_MODE is true; ignored in production. Leave empty to resolve
# the tier from the org's license as usual.
# (type: enum=free|trial|paid)
GLOBAL_RULES_IMPORT_TIER_OVERRIDE=

# Run TypeORM migrations on container boot (OLTP + analytics warehouse +
# mcp-manager). Default true so a fresh install boots into a usable
# state without an extra step. Set to false to manage migrations
# manually (e.g. blue/green deploys where you run them out-of-band).
# (type: boolean)
RUN_MIGRATIONS=true

# Run database seeds on container boot. Required for first-time setup
# (creates default org, admin role, etc). Idempotent — safe to leave on.
# (type: boolean)
RUN_SEEDS=true

# ============================================================
# Server
# ============================================================

GLOBAL_API_CONTAINER_NAME=kodus_api

API_HOST=0.0.0.0

# (type: port)
API_PORT=3001

# (type: port)
API_WEBHOOKS_PORT=3332

# (type: number)
API_RATE_MAX_REQUEST=100

# Rate limit interval in milliseconds.
# (type: number)
API_RATE_INTERVAL=1000

# Public URL of the API. Required by EE SSO/SAML (libs/ee/sso/) — must be the
# browser-reachable URL that IdPs redirect back to. Cloud sets via infra;
# self-hosted Enterprise sets in their .env when enabling SSO.
# (type: url)
API_URL=http://localhost:3001

# Public URL of the web frontend.
# (type: url)
API_FRONTEND_URL=http://localhost:3000

# ============================================================
# API Docs (Swagger / OpenAPI)
# ============================================================

# (type: boolean)
API_DOCS_ENABLED=false

API_DOCS_PATH=/docs

API_DOCS_SPEC_PATH=/openapi.json

# Basic auth user for /docs (leave empty to keep it open).
API_DOCS_BASIC_USER=

# (secret)
API_DOCS_BASIC_PASS=op://Kodus-Dev/API_DOCS_BASIC_PASS/password

# ============================================================
# Postgres (primary OLTP)
# ============================================================

# Postgres connection URI — alternative to API_PG_DB_*. When set, the app
# IGNORES the individual host/port/user/pass/database vars below and connects
# via this URI instead. Useful for managed Postgres providers (Heroku, Railway,
# Supabase, RDS) that hand you a single string.
# Hierarchy: DATABASE_URL → API_PG_DB_URL → individual vars.
# (secret, type: url)
DATABASE_URL=op://Kodus-Dev/DATABASE_URL/password

# Redundant alias for DATABASE_URL — same effect, second in the lookup chain.
# (secret, type: url)
API_PG_DB_URL=op://Kodus-Dev/API_PG_DB_URL/password

API_PG_DB_HOST=db_postgres

# (type: port)
API_PG_DB_PORT=5432

API_PG_DB_USERNAME=kodusdev

# (required, secret)
API_PG_DB_PASSWORD=123456

API_PG_DB_DATABASE=kodus_db

# ============================================================
# MongoDB
# ============================================================

# Mongo connection URI — alternative to API_MG_DB_*. When set, IGNORES the
# individual vars and connects via this URI. Useful for Atlas / managed Mongo.
# Hierarchy: MONGODB_URI → API_MG_DB_URI → individual vars.
# (secret, type: url)
MONGODB_URI=op://Kodus-Dev/MONGODB_URI/password

# Redundant alias for MONGODB_URI — same effect, second in the lookup chain.
# (secret, type: url)
API_MG_DB_URI=op://Kodus-Dev/API_MG_DB_URI/password

API_MG_DB_HOST=db_mongodb

# (type: port)
API_MG_DB_PORT=27017

API_MG_DB_USERNAME=kodusdev

# (required, secret)
API_MG_DB_PASSWORD=123456

API_MG_DB_DATABASE=kodus_db

API_MG_DB_AUTH_SOURCE=

# Used when API_NODE_ENV=production.
API_MG_DB_PRODUCTION_CONFIG=

# ============================================================
# RabbitMQ
# ============================================================

# (type: boolean)
API_RABBITMQ_ENABLED=true

RABBITMQ_DEFAULT_USER=dev

# (secret)
RABBITMQ_DEFAULT_PASS=devpass

RABBITMQ_HOSTNAME=rabbitmq-local

# Connection URI — keep in sync with user/pass/hostname above.
# (secret, type: url)
API_RABBITMQ_URI=amqp://dev:devpass@rabbitmq-local:5672/kodus-ai?heartbeat=60

# ============================================================
# Workflow Queue tuning
# ============================================================

# Selects which workload this worker container handles. The kodus-worker
# image refuses to boot without this — and the queues it owns (workflow.jobs.*)
# are created on its first connection, so if the worker dies on boot the
# api/webhooks fail with QueueBind 404 on every webhook event. Every
# deployment runs code-review; analytics is a separate Cockpit worker when
# that feature is enabled.
# (required, type: enum(code-review,analytics))
WORKER_ROLE=code-review

# (type: number)
WORKFLOW_QUEUE_WORKER_PREFETCH=20

# (type: number)
WORKFLOW_QUEUE_PUBLISHER_PREFETCH=5

# (type: number)
WORKFLOW_QUEUE_WEBHOOK_PREFETCH=20

# (type: number)
WORKFLOW_QUEUE_CODE_REVIEW_PREFETCH=20

# (type: number)
WORKFLOW_QUEUE_WEBHOOK_PROCESS_TIMEOUT_MS=600000

# (type: number)
WORKFLOW_QUEUE_CODE_REVIEW_PROCESS_TIMEOUT_MS=7200000

# Max retries before a message is marked FAILED.
# (type: number)
WORKFLOW_OUTBOX_MAX_ATTEMPTS=10

# ============================================================
# JWT
# ============================================================

API_JWT_EXPIRES_IN=365d

# (required, secret)
API_JWT_SECRET=op://Kodus-Dev/API_JWT_SECRET/password

# JWT refresh token signing secret. Read by libs/core/infrastructure/config/
# loaders/jwt.config.loader.ts. Note: name is API_JWT_REFRESH_SECRET (with
# underscore). The legacy name API_JWT_REFRESHSECRET (without underscore)
# was a typo and is no longer read by code.
# (required, secret)
API_JWT_REFRESH_SECRET=op://Kodus-Dev/API_JWT_REFRESH_SECRET/password

# Cloud uses long-lived refresh (365d); self-hosted hardens to 7d. Override
# either side here without touching the other.
API_JWT_REFRESH_EXPIRES_IN=365d

# RSA private key (PEM) used to sign RS256 tokens for integrated products
# (e.g. kodus-helpdesk cloud SSO). Newlines must be escaped as \n in the env
# value. The matching public key is configured in the consuming service.
# (secret)
API_JWT_PRIVATE_KEY=op://Kodus-Dev/API_JWT_PRIVATE_KEY/password

# Symmetric key for column-level encryption (DB).
# (required, secret)
API_CRYPTO_KEY=op://Kodus-Dev/API_CRYPTO_KEY/password

# ============================================================
# LLM providers
# ============================================================

# OpenAI API key. Required when API_LLM_PROVIDER_MODEL targets an OpenAI model.
# (secret)
API_OPEN_AI_API_KEY=op://Kodus-Dev/API_OPEN_AI_API_KEY/password

# OpenAI-compatible endpoint override (e.g. point to a local model proxy).
# (type: url)
API_OPENAI_FORCE_BASE_URL=

# Comma-separated baseURL substrings trusted for native json_schema
# structured output on BYOK openai_compatible providers. A capability
# allowlist: when a BYOK baseURL contains one of these, the code review
# agent sends response_format=json_schema instead of the slower
# json_object fallback. Leave empty unless you run a non-vLLM but
# schema-capable proxy.
API_TRUST_JSON_SCHEMA_BASE_URLS=

# Force a specific model. "auto" = router picks per task.
API_LLM_PROVIDER_MODEL=auto

# Override the temperature for every LLM call (env-mode self-hosted only).
# Set this if `API_LLM_PROVIDER_MODEL` points at a reasoning/thinking
# model whose API restricts temperature (Moonshot's `kimi-k2.6` and
# `kimi-k2-thinking*` only accept temperature=1; OpenAI's o1 family is
# similar). When unset/empty, Kodus auto-clamps a small list of known
# reasoning models to 1 and falls through to each prompt's
# `setTemperature()` for everything else. Consumed by
# libs/code-review/.../env-llm-config.ts and surfaced in
# get-llm-config-status so the dashboard can explain why every prompt
# ignores its hard-coded temperature.
# (type: number)
API_LLM_TEMPERATURE_OVERRIDE=

# (secret)
API_ANTHROPIC_API_KEY=op://Kodus-Dev/API_ANTHROPIC_API_KEY/password

# Optional secondary providers — appear commented in the installer template.
# (secret)
API_GOOGLE_AI_API_KEY=op://Kodus-Dev/API_GOOGLE_AI_API_KEY/password

# (secret)
GEMINI_API_KEY=op://Kodus-Dev/GEMINI_API_KEY/password

# Service Account JSON (base64-encoded) for Vertex AI.
# Leave empty to authenticate with Application Default Credentials instead
# (Workload Identity, an attached service account, or `gcloud auth
# application-default login`); GOOGLE_CLOUD_PROJECT must then be set.
# (secret)
API_VERTEX_AI_API_KEY=op://Kodus-Dev/API_VERTEX_AI_API_KEY/password

# GCP project for Vertex AI when authenticating with Application Default
# Credentials rather than a service account key. Only needed when
# API_VERTEX_AI_API_KEY is empty — with a key the project is read from the
# key itself. GCLOUD_PROJECT is accepted as an alias.
GOOGLE_CLOUD_PROJECT=

API_VERTEX_AI_LOCATION=us-central1

# Google AI provider: gemini (AI Studio) or vertex (Vertex AI).
# (type: enum(gemini,vertex))
API_GOOGLE_AI_PROVIDER=gemini

# (secret)
API_NOVITA_AI_API_KEY=op://Kodus-Dev/API_NOVITA_AI_API_KEY/password

# Moonshot AI (Kimi) — used by the public-demo trial flow in
# libs/code-review/infrastructure/agents/llm/byok-to-vercel.ts when the
# default model name matches /^kimi[-_.]/. Wires through the OpenAI-
# compatible adapter pointed at https://api.moonshot.ai/v1. The eval
# scripts (evals/{investigation,promotion}/run-eval.js) also reference
# this key by name. Cloud-only — self-hosted has no Moonshot demo path.
# (secret)
API_MOONSHOT_API_KEY=op://Kodus-Dev/API_MOONSHOT_API_KEY/password

# Fireworks AI — the managed default model (deepseek-v4-flash hosted on
# Fireworks) for the trial / no-BYOK flow: libs/llm/byok-to-vercel.ts routes
# any default model name matching /^accounts\/fireworks\/models\// through the
# OpenAI-compatible adapter pointed at API_FIREWORKS_BASE_URL. Used by the v5
# code-review agents, PR summary, kody-rules generation, reference detection,
# and issue generation/closing. Cloud-only — self-hosted brings its own model
# via API_LLM_PROVIDER_MODEL.
# (secret)
API_FIREWORKS_API_KEY=op://Kodus-Dev/API_FIREWORKS_API_KEY/password

# (type: url)
API_FIREWORKS_BASE_URL=https://api.fireworks.ai/inference/v1

# DeepSeek — legacy managed fallback. Kept only for any lingering explicit
# deepseek-* overrides; the default trial path now routes through Fireworks.
# (secret)
API_DEEPSEEK_API_KEY=op://Kodus-Dev/API_DEEPSEEK_API_KEY/password

# (type: url)
API_DEEPSEEK_BASE_URL=https://api.deepseek.com/v1

# (type: url)
API_GROQ_BASE_URL=https://api.groq.com/openai/v1

# (secret)
API_GROQ_API_KEY=op://Kodus-Dev/API_GROQ_API_KEY/password

# OpenRouter API key. Used by BYOK provider in
# libs/organization/.../get-models-by-provider.use-case.ts.
# (secret)
API_OPEN_ROUTER_API_KEY=op://Kodus-Dev/API_OPEN_ROUTER_API_KEY/password

# MorphLLM (fast-apply model). When set, the review pipeline uses MorphLLM
# to apply LLM-suggested code edits automatically and reliably (better than
# letting the main LLM rewrite files). Used in
# libs/code-review/pipeline/stages/validate-suggestions.stage.ts. Without it,
# the "apply suggested fix" feature falls back to the main LLM with lower
# accuracy.
# (secret)
API_MORPHLLM_API_KEY=op://Kodus-Dev/API_MORPHLLM_API_KEY/password

# Exa (semantic web search). When set, code-review agents can search external
# documentation during review (e.g. fetch docs about a library API the PR
# uses). Used in libs/code-review/infrastructure/adapters/services/documentation-
# search-exa.service.ts and the agent providers. Without it, agents skip the
# documentation-fetching loop and review using only repo context.
# (secret)
API_EXA_KEY=op://Kodus-Dev/API_EXA_KEY/password

# ============================================================
# Git providers — webhooks + OAuth
# ============================================================

# Optional Git provider OAuth/App config — documented for self-hosted users
# in the docs reference, not in the default installer template.
GLOBAL_GITHUB_CLIENT_ID=

# (secret)
API_GITHUB_CLIENT_SECRET=op://Kodus-Dev/API_GITHUB_CLIENT_SECRET/password

# (secret)
API_GITHUB_PRIVATE_KEY=op://Kodus-Dev/API_GITHUB_PRIVATE_KEY/password

# (type: url)
API_GITHUB_CODE_MANAGEMENT_WEBHOOK=http://localhost:3001/github/webhook

# (secret)
GITHUB_TOKEN=op://Kodus-Dev/GITHUB_TOKEN/password

API_GITHUB_APP_ID=

GLOBAL_GITLAB_CLIENT_ID=

# (secret)
GLOBAL_GITLAB_CLIENT_SECRET=op://Kodus-Dev/GLOBAL_GITLAB_CLIENT_SECRET/password

# (type: url)
GLOBAL_GITLAB_REDIRECT_URL=

# (type: url)
API_GITLAB_CODE_MANAGEMENT_WEBHOOK=http://localhost:3001/gitlab/webhook

# (type: url)
GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK=http://localhost:3001/bitbucket/webhook

# Minimum interval (ms) between Bitbucket API calls per worker instance.
# In-memory rate gate to keep us under Bitbucket's per-minute throttle.
# Note: this is per-replica — with N workers the effective rate is N×
# whatever you set here. 400ms is safe for typical multi-replica setups;
# raise it if a customer's Bitbucket instance throttles aggressively.
# (type: number)
BITBUCKET_RATE_GATE_MIN_INTERVAL_MS=400

# How many times to retry a Bitbucket call that returns HTTP 429 (honouring
# Retry-After) before giving up. Reviews legitimately burst past Bitbucket
# Cloud's ~1000 req/hour ceiling; retrying keeps them alive instead of
# failing the review. 4 attempts covers the worst observed throttle windows.
# (type: number)
BITBUCKET_RATE_GATE_429_MAX_RETRIES=4

# (type: url)
GLOBAL_AZURE_REPOS_CODE_MANAGEMENT_WEBHOOK=http://localhost:3001/azure-repos/webhook

# (type: url)
API_FORGEJO_CODE_MANAGEMENT_WEBHOOK=http://localhost:3001/forgejo/webhook

# Shared secret used to sign internal webhook calls.
# (required, secret)
CODE_MANAGEMENT_SECRET=op://Kodus-Dev/CODE_MANAGEMENT_SECRET/password

# (secret)
CODE_MANAGEMENT_WEBHOOK_TOKEN=op://Kodus-Dev/CODE_MANAGEMENT_WEBHOOK_TOKEN/password

# Discord channel webhook used to deliver "Request more trial reviews" form
# submissions to our team. Optional — when unset the request fails honestly
# and the UI tells the user the channel is not configured.
# (secret)
API_DISCORD_TRIAL_REQUEST_WEBHOOK_URL=op://Kodus-Dev/API_DISCORD_TRIAL_REQUEST_WEBHOOK_URL/password

# ============================================================
# Observability
# ============================================================

# Enables the MongoDB observability exporter used for logs/telemetry persistence.
# Set to false to disable Mongo observability writes without disabling the
# application's MongoDB connection itself.
# (type: boolean)
OBSERVABILITY_MONGO_ENABLED=true

# Langfuse tracing — opt-in for self-hosted (cloud Langfuse needs the user's
# own keys; default is to leave it off in self-hosted).
# (type: boolean)
LANGFUSE_TRACING=true

LANGFUSE_PUBLIC_KEY=

# (secret)
LANGFUSE_SECRET_KEY=op://Kodus-Dev/LANGFUSE_SECRET_KEY/password

# (type: url)
LANGFUSE_BASE_URL=https://cloud.langfuse.com

LANGFUSE_ENVIRONMENT=development

# BetterStack / Sentry — Kodus-internal incident reporting. Cloud-only.
# (secret, type: url)
API_BETTERSTACK_DSN=op://Kodus-Dev/API_BETTERSTACK_DSN/password

SENTRY_RELEASE=

# Pyroscope profiling — opt-in for self-hosted (requires extra container).
# (type: url)
PYROSCOPE_SERVER_ADDRESS=http://pyroscope:4040

# (type: boolean)
PYROSCOPE_HEAP_PROFILING=false

# PostHog — Kodus-internal product analytics. Cloud-only.
# (secret)
API_POSTHOG_KEY=op://Kodus-Dev/API_POSTHOG_KEY/password

# ============================================================
# Sandbox (cross-file context, agent verification)
# ============================================================

# Provider: auto | e2b | local | none.
# (type: enum(auto,e2b,local,none))
SANDBOX_PROVIDER=e2b

# Required when SANDBOX_PROVIDER=e2b.
# (secret)
API_E2B_KEY=op://Kodus-Dev/API_E2B_KEY/password

API_E2B_TEMPLATE_ID=

API_E2B_TEMPLATE_GRAPH_ID=

# ============================================================
# Cron schedules (UTC)
# ============================================================

# Daily at 00:00.
# (type: cron)
API_CRON_SYNC_CODE_REVIEW_REACTIONS="0 0 * * *"

# Saturday at 00:00.
# (type: cron)
API_CRON_KODY_LEARNING="0 0 * * 6"

# Every 2 minutes.
# (type: cron)
API_CRON_CHECK_IF_PR_SHOULD_BE_APPROVED="*/2 * * * *"

# 1st of each month at 09:00 UTC — org review report email.
# (type: cron)
API_CRON_ORG_REPORT="0 9 1 * *"

# 1st & 16th at 09:00 UTC — per-repo review digest email (biweekly).
# (type: cron)
API_CRON_REPO_REPORT="0 9 1,16 * *"

# Every hour
# (type: cron)
API_CRON_SPEND_LIMIT_ALERT="0 * * * *"

# ============================================================
# Email (Resend — https://resend.com / SMTP)
# ============================================================

# Notifications email provider
# (type: enum(resend,smtp))
API_NOTIFICATION_EMAIL_PROVIDER=resend

# Resend — Kodus-managed email sender.
# (secret)
RESEND_API_KEY=op://Kodus-Dev/RESEND_API_KEY/password

# Destination address used by scripts/dev/test-emails.ts when smoke-
# testing transactional email delivery. Dev-only utility — production
# code doesn't read this. Cloud-only because the test script targets
# the Kodus-managed Resend setup.
# (type: email)
RESEND_TEST_EMAIL=

# (type: url)
API_USER_INVITE_BASE_URL=http://localhost:3000

# ============================================================
# AWS / S3
# ============================================================

# S3 / AWS — Kodus-managed asset bucket. Cloud-only.
API_AWS_REGION=us-east-1

API_AWS_USERNAME=

# (secret)
API_AWS_PASSWORD=op://Kodus-Dev/API_AWS_PASSWORD/password

API_AWS_BUCKET_NAME_ASSISTANT=kodus-assistant-files

# ============================================================
# Web frontend
# ============================================================

# (type: enum(self-hosted,development,production))
WEB_NODE_ENV=development

WEB_HOSTNAME_API=localhost

# (type: port)
WEB_PORT_API=3001

# (type: port)
WEB_PORT=3000

# Generate with: openssl rand -base64 32. Must equal NEXTAUTH_SECRET — the
# installer's generate-secrets.sh mirrors them automatically.
# (required, secret)
WEB_NEXTAUTH_SECRET=op://Kodus-Dev/WEB_NEXTAUTH_SECRET/password

# (type: url)
NEXTAUTH_URL=http://localhost:3000

# (type: url)
WEB_GITHUB_INSTALL_URL=

WEB_OAUTH_GITHUB_CLIENT_ID=

# (secret)
WEB_OAUTH_GITHUB_CLIENT_SECRET=op://Kodus-Dev/WEB_OAUTH_GITHUB_CLIENT_SECRET/password

# ============================================================
# Support links (cosmetic)
# ============================================================

# (type: url)
WEB_SUPPORT_DOCS_URL=https://docs.kodus.io

# (type: url)
WEB_SUPPORT_DISCORD_INVITE_URL=https://discord.gg/QFzwwmNmdN

# (type: url)
WEB_SUPPORT_TALK_TO_FOUNDER_URL=https://cal.com/gabrielmalinosqui/30min

# Connection to the analytics Postgres. In cloud / self-hosted-enterprise
# this is a dedicated instance (deploy env overrides these). For local
# docker dev the defaults reuse the main OLTP container (db_postgres) — an
# empty value here would defeat the loader's `??` fallback and resolve to
# loopback, so we set the dev values explicitly.
ANALYTICS_PG_DB_HOST=db_postgres

# (type: port)
ANALYTICS_PG_DB_PORT=5432

ANALYTICS_PG_DB_USERNAME=kodusdev

# (secret)
ANALYTICS_PG_DB_PASSWORD=123456

ANALYTICS_PG_DB_DATABASE=kodus_db

# Schema name in the analytics Postgres (default: analytics). Legacy alias
# of API_PG_ANALYTICS_SCHEMA — both work; loader prefers ANALYTICS_PG_DB_*
# when set, then falls back to API_PG_ANALYTICS_*.
ANALYTICS_PG_DB_SCHEMA=analytics

# Upper bound on the analytics Postgres pool.
ANALYTICS_PG_POOL_MAX=5

# Cron expression — analytics ingestion. Default = every 30 min.
# (type: cron)
ANALYTICS_INGESTION_CRON="*/30 * * * *"

# Kill switch for the ingestion cron regardless of role.
# (type: boolean)
ANALYTICS_INGESTION_DISABLED=false

# Run one ingestion pass on worker boot instead of waiting for the first
# scheduled cron tick (so a fresh install / restart catches up immediately).
# Opt-out only: set 'false' to skip the boot pass. Default = run on boot.
# (type: boolean)
ANALYTICS_INGESTION_RUN_ON_BOOT=true

# Cron — LLM-based PR type classifier (analytics worker role).
# (type: cron)
ANALYTICS_CLASSIFIER_CRON="*/15 * * * *"

# Kill switch for the classifier.
# (type: boolean)
ANALYTICS_CLASSIFIER_DISABLED=false

# Alternative naming used by some loaders. Verify if duplicate of ANALYTICS_PG_DB_*.
API_PG_ANALYTICS_HOST=

# (type: port)
API_PG_ANALYTICS_PORT=5432

API_PG_ANALYTICS_USERNAME=

# (secret)
API_PG_ANALYTICS_PASSWORD=op://Kodus-Dev/API_PG_ANALYTICS_PASSWORD/password

API_PG_ANALYTICS_DATABASE=

# Schema name for analytics tables (default: "analytics").
API_PG_ANALYTICS_SCHEMA=analytics

# ============================================================
# BetterStack heartbeats (cloud-only)
# ============================================================

# (secret)
API_BETTERSTACK_API_TOKEN=op://Kodus-Dev/API_BETTERSTACK_API_TOKEN/password

# (type: url)
API_BETTERSTACK_HEARTBEAT_ERROR_RATE_URL=

# (type: url)
API_BETTERSTACK_HEARTBEAT_OUTBOX_URL=

# (type: url)
API_BETTERSTACK_HEARTBEAT_REVIEW_MONITOR_URL=

# (type: url)
API_BETTERSTACK_HEARTBEAT_WEBHOOK_URL=

# ============================================================
# Cloud-only services (Kodus-managed)
# ============================================================

# n8n internal lifecycle webhook (Kodus telemetry pipeline).
# (type: url)
API_SIGNUP_NOTIFICATION_WEBHOOK=

# Kodus T&C URL shown in the cloud frontend.
# (type: url)
WEB_TERMS_AND_CONDITIONS=

# Frontend product analytics (PostHog).
# (secret)
WEB_POSTHOG_KEY=op://Kodus-Dev/WEB_POSTHOG_KEY/password

# Billing service (Kodus-managed cloud-only).
GLOBAL_BILLING_CONTAINER_NAME=kodus-service-billing

GLOBAL_KODUS_SERVICE_BILLING=http://kodus-service-billing:3992

WEB_HOSTNAME_BILLING=localhost

# (type: port)
WEB_PORT_BILLING=3992

# Shared secret used to verify HMAC-SHA256 signatures on inbound
# notification webhooks from the billing service
# (e.g. payment-failed, trial-expiring).
# (secret)
API_BILLING_WEBHOOK_SECRET=op://Kodus-Dev/API_BILLING_WEBHOOK_SECRET/password

# ============================================================
# Optional advanced config — documented in docs, not in default template
# ============================================================

# Google OAuth (social login). Self-hosted user fills in if they want it.
API_GOOGLE_CLIENT_ID=

# (secret)
API_GOOGLE_CLIENT_SECRET=op://Kodus-Dev/API_GOOGLE_CLIENT_SECRET/password

# GitLab OAuth token URL override.
# (type: url)
API_GITLAB_TOKEN_URL=

WEB_OAUTH_GITLAB_CLIENT_ID=

# (secret)
WEB_OAUTH_GITLAB_CLIENT_SECRET=op://Kodus-Dev/WEB_OAUTH_GITLAB_CLIENT_SECRET/password

# (type: url)
WEB_GITLAB_OAUTH_URL=https://gitlab.com/oauth/authorize

WEB_GITLAB_SCOPES="read_api read_user read_repository"

# (type: url)
WEB_BITBUCKET_INSTALL_URL=

# MCP Manager service container — built and deployed alongside the other
# kodus-ai apps (apps/mcp-manager). Cloud reads these for in-network
# routing; self-hosted's installer wires them in docker-compose.
WEB_HOSTNAME_MCP_MANAGER=localhost

# (type: port)
WEB_PORT_MCP_MANAGER=3101

GLOBAL_MCP_MANAGER_CONTAINER_NAME=kodus-mcp-manager

# ============================================================
# Doc links shown in the UI when configuring providers
# ============================================================

# (type: url)
WEB_TOKEN_DOCS_GITHUB=https://docs.kodus.io/how_to_use/en/code_review/general_config/github_pat

# (type: url)
WEB_TOKEN_DOCS_GITLAB=https://docs.kodus.io/how_to_use/en/code_review/general_config/gitlab_pat

# (type: url)
WEB_TOKEN_DOCS_BITBUCKET=https://docs.kodus.io/how_to_use/en/code_review/general_config/bitbucket_pat

# (type: url)
WEB_TOKEN_DOCS_AZUREREPOS=https://docs.kodus.io/how_to_use/en/code_review/general_config/azure_devops_pat

# (type: url)
WEB_TOKEN_DOCS_FORGEJO=

# ============================================================
# Cockpit / analytics service — Self-hosted Enterprise
# ============================================================

GLOBAL_ANALYTICS_CONTAINER_NAME=kodus-service-analytics

WEB_ANALYTICS_HOSTNAME=

# (secret)
WEB_ANALYTICS_SECRET=op://Kodus-Dev/WEB_ANALYTICS_SECRET/password

# (type: port)
WEB_PORT_ANALYTICS=3005

# Enables the MCP integration in kodus-ai (calls into the MCP Manager service).
# When false, MCP-related code paths are skipped entirely.
# (type: boolean)
API_MCP_SERVER_ENABLED=false

# Address of the kodus-mcp-manager service (sibling container).
# kodus-ai calls this URL to provision MCP servers per organization.
# In docker-compose self-hosted installs, the worker and mcp-manager run
# in sibling containers — `localhost` inside the worker resolves to the
# worker itself, not to the mcp-manager, and pipeline stages that call
# `MCPManagerService.getConnections()` 400 with ECONNREFUSED. Always use
# the compose service name (`kodus-mcp-manager`) so the request reaches
# the right container.
# (type: url)
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101

# Public URL where MCP clients (e.g. Cursor/Claude Desktop) connect to
# consume MCP tools exposed by kodus-ai itself.
# (type: url)
API_KODUS_MCP_SERVER_URL=http://kodus_api:3001/mcp

# Symmetric key used by MCP Manager to encrypt tokens at rest.
# Generate with: openssl rand -base64 32
# (secret)
API_MCP_MANAGER_ENCRYPTION_SECRET=op://Kodus-Dev/API_MCP_MANAGER_ENCRYPTION_SECRET/password

# ============================================================
# Auth — additional libs that read their own env keys
# ============================================================

# NextAuth.js secret — separate from WEB_NEXTAUTH_SECRET. Some NextAuth
# code paths (server-side session, JWT signing) read NEXTAUTH_SECRET
# directly even when the rest of the app uses WEB_NEXTAUTH_SECRET. Set
# both to the same value to keep them aligned (the installer's
# generate-secrets.sh does the mirroring automatically).
# (required, secret)
NEXTAUTH_SECRET=op://Kodus-Dev/NEXTAUTH_SECRET/password

# ============================================================
# Postgres — extra flags
# ============================================================

# Force-enable SSL on the main Postgres connection. When unset, SSL is
# inferred from API_DATABASE_ENV (production/homolog → on; dev → off).
# Use this only when you need to override the inferred default.
# (type: boolean)
API_PG_DB_SSL=

# ============================================================
# API Docs — additional config
# ============================================================

# Override the base URL Swagger UI advertises in the spec — useful when
# the API sits behind a proxy and the UI is loaded from a different host.
# (type: url)
API_DOCS_BASE_URL=

# Comma-separated list of server URLs to advertise in the OpenAPI spec
# (matches the OpenAPI `servers` array). Format: "url1,url2|description2".
API_DOCS_SERVER_URLS=

# ============================================================
# Cron schedules — cloud-only crons
# ============================================================

# Reclassifies orphaned (no-PR) review sessions every 15 minutes.
# Cloud-only feature.
# (type: cron)
API_CRON_CLASSIFY_ORPHANED_SESSIONS="0 */15 * * * *"

# Daily cleanup of expired SSO test sessions (1 AM UTC).
# (type: cron)
API_CRON_SSO_TEST_SESSION_CLEANUP="0 1 * * *"

# Reaps code review executions stuck IN_PROGRESS (process died mid-review)
# and finalizes their orphaned platform check runs.
# (type: cron)
API_CRON_STALE_REVIEW_WATCHDOG="*/30 * * * *"

# Daily sweep (4 AM) that releases license seats still held by users who left
# the git organization. Only acts on orgs that opted in via the
# auto_license_assignment parameter, and skips any org whose member list could
# not be fetched, so a provider outage never mass-revokes seats.
# (type: cron)
API_CRON_PRUNE_LICENSE_SEATS="0 4 * * *"

# Cadence of the workflow-jobs stale-PROCESSING reaper, which fails jobs
# left in PROCESSING when a worker was killed mid-processing (OOM/eviction).
# The eligibility threshold (WORKFLOW_STALE_JOB_TIMEOUT_MINUTES) still bounds
# what can be reaped, so cadence only affects how quickly orphans are caught.
# (type: cron)
WORKFLOW_STALE_JOB_REAPER_CRON="0 */10 * * * *"

# Minutes a workflow job may sit in PROCESSING before the reaper marks it
# FAILED. Must exceed the longest legitimate run — the 105min job-abort
# timeout and the 150min inbox claim timeout — so live jobs are never reaped;
# 180 leaves margin.
# (type: number)
WORKFLOW_STALE_JOB_TIMEOUT_MINUTES=180

# Per-handler prefetch (in-flight messages) for the check-implementation
# workflow handler.
# (type: number)
WORKFLOW_QUEUE_CHECK_IMPLEMENTATION_PREFETCH=20

# Hard timeout (ms) for a check-implementation handler invocation.
# (type: number)
WORKFLOW_QUEUE_CHECK_IMPLEMENTATION_TIMEOUT_MS=600000

# Per-handler prefetch for the feedback workflow handler.
# (type: number)
WORKFLOW_QUEUE_FEEDBACK_PREFETCH=20

# Hard timeout (ms) for any workflow handler invocation (fallback).
# (type: number)
WORKFLOW_QUEUE_HANDLER_TIMEOUT_MS=60000

# Max retries before a workflow message is sent to the DLQ.
# (type: number)
WORKFLOW_QUEUE_WORKER_MAX_RETRIES=3

# Backoff between worker retries, in milliseconds.
# (type: number)
WORKFLOW_QUEUE_WORKER_RETRY_DELAY_MS=5000

# Auto-scale: enable adaptive worker pool based on queue depth.
# (type: boolean)
WORKFLOW_QUEUE_AUTO_SCALE_ENABLED=false

# Auto-scale: lower bound on worker count.
# (type: number)
WORKFLOW_QUEUE_AUTO_SCALE_MIN_WORKERS=1

# Auto-scale: upper bound on worker count.
# (type: number)
WORKFLOW_QUEUE_AUTO_SCALE_MAX_WORKERS=10

# Auto-scale: spin up another worker when queue depth exceeds this.
# (type: number)
WORKFLOW_QUEUE_AUTO_SCALE_QUEUE_THRESHOLD=50

# Circuit breaker: open after N consecutive handler failures.
# (type: number)
WORKFLOW_QUEUE_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5

# Circuit breaker: hold open for this long (ms) before half-open probe.
# (type: number)
WORKFLOW_QUEUE_CIRCUIT_BREAKER_TIMEOUT_MS=60000

# ============================================================
# Misc runtime flags
# ============================================================

# Force the new agent-based code review engine on for ALL orgs in this
# instance (bypasses the PostHog feature flag). Set "true" to enable.
# Read by libs/core/providers/code-review-pipeline.provider.ee.ts —
# .ee.ts file means it only takes effect in EE contexts.
# (type: boolean)
API_AGENT_REVIEW_ENABLED=true

# Wait for RabbitMQ to become reachable before completing app boot.
# (type: boolean)
API_RABBITMQ_WAIT=true

# Worker drain timeout (ms) — how long to keep accepting in-flight jobs
# during graceful shutdown before forcing exit.
# (type: number)
API_WORKER_DRAIN_TIMEOUT_MS=600000

# ============================================================
# Self-hosted telemetry
# ============================================================

# Opt out of the daily anonymous heartbeat sent to telemetry.kodus.io.
# Cloud is unaffected — the cron skips when API_CLOUD_MODE=true regardless.
# The heartbeat runs from the mandatory code-review worker, so community and
# enterprise self-hosted installs are covered. Self-hosted operators flip this
# to "true" to disable. The payload is aggregated counters (active users, PRs
# reviewed, repos connected, etc.) plus runtime metadata (Node version, OS,
# deployment). It never includes emails, repo/branch/PR names, code, or any
# identifying data. Full schema published at
# https://github.com/kodustech/kodus-beacon/blob/main/docs/api.md
# (type: boolean)
KODUS_TELEMETRY_DISABLED=false

# Optional receiver endpoint override for tests or controlled internal
# deployments. Leave empty in production to use
# https://telemetry.kodus.io/v1/heartbeat.
# (type: url)
KODUS_TELEMETRY_ENDPOINT=

# ============================================================
# MCP — additional client config
# ============================================================

# Backend URL the mcp-manager service exposes for upstream callers
# (cloud-internal). Distinct from API_KODUS_SERVICE_MCP_MANAGER which
# is the address kodus-ai uses to call mcp-manager.
# (type: url)
API_MCP_MANAGER_BACKEND_URL=

# ============================================================
# Web — additional pages/services
# ============================================================

# Helpdesk service hostname (web frontend reads this to render help links).
WEB_HOSTNAME_HELPDESK=localhost

# (type: port)
WEB_PORT_HELPDESK=3004

# Documentation URL for the rule-files detection feature, shown in the
# web UI when a user is configuring code review rules.
# (type: url)
WEB_RULE_FILES_DOCS=https://docs.kodus.io/how_to_use/en/code_review/configs/rules_file_detection