KiCI environment variable reference

Catalog of the environment variables shared across the customer-deployable KiCI services, plus the rotated-file logger knobs. Per-service variables live in each service’s configuration doc (linked below). Generated from the Zod schemas in each service’s config.ts. The orchestrator and agent reject unknown KICI_* env vars at boot (typo catcher) — set KICI_DEV=true to downgrade to a warning during local development.

Per-service environment variables

Variables specific to one service are documented in that service’s config reference:

• Agent configuration — agent-specific env vars.
• Orchestrator configuration — orchestrator-specific env vars.

Common environment variables

These variables are read identically by every KiCI service that defines them (same type, same default). They are documented here once rather than duplicated in each service’s config doc.

Env var	Required	Default	Type	Aliases	Description
KICI_CONCURRENCY_WAIT_TIMEOUT_MS	no	3600000	number
KICI_JOB_HEARTBEAT_INTERVAL_MS	no	60000	number
KICI_LOG_LEVEL	no	”info”	enum:debug|info|warn|error
OTEL_EXPORTER_OTLP_ENDPOINT	no		string

Logger / shared (@kici-dev/shared)

Read by the rotated-file logger (packages/shared/src/logger.ts) before any service config loads. Setting KICI_LOG_DIR enables the JSON file transport; the instance-id env vars only act as a filename suffix (so multiple processes can share one KICI_LOG_DIR).

Env var	Required	Default	Type	Aliases	Description
KICI_CLUSTER_INSTANCE_ID	no		string		Stable orchestrator identifier; appended to the log filename so multiple instances can share one KICI_LOG_DIR.
KICI_AGENT_ID	no		string		Stable agent identifier; appended to the agent log filename so multiple agents can share one KICI_LOG_DIR.
KICI_LOG_DIR	no		string		Directory for rotated JSON log files. When unset, the logger only writes to stdout/stderr.
KICI_LOG_FORMAT	no	”auto”	enum:auto|plain|json		Output format for stdout/stderr. auto (default) emits JSON when stdout is piped and plain coloured text when stdout is a TTY. plain and json force the corresponding format regardless of TTY. Runtime services (orchestrator, agent, platform, dashboard SSR) pin json so a journal-attached PTY cannot flip them into plain mode.
KICI_LOG_MAX_SIZE	no	”500m”	string		Per-file size cap for rotated logs. Accepts a numeric byte count or a size suffix (k, m, g).
KICI_LOG_RETENTION_DAYS	no	7	number		How many days of rotated logs to keep before deletion.
KICI_PLATFORM_INSTANCE_ID	no		string		Stable Platform identifier; appended to the platform log filename so multiple instances can share one KICI_LOG_DIR.