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 before any service config loads: KICI_LOG_DIR and the instance-id variables by the rotated-file logger (packages/core/src/logger.ts), KICI_TMPDIR by the temp-directory helper, and KICI_ENV_FILE by the orchestrator and agent entry points. 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_ENV_FILE	no		string		Path of an env file the orchestrator or agent loads when it starts, before it reads any other setting. The Windows service installer sets it, so the service registration carries the path and not the values. Each KEY=value line overrides the inherited value, and PATH lines go in front of the inherited PATH. The process removes the variable once the file is loaded. On Windows, when the file sets a variable that Node.js reads only as it starts, such as NODE_OPTIONS or NODE_EXTRA_CA_CERTS, the process starts again with the loaded environment.
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.
KICI_TMPDIR	no		string		Base directory for KiCI-created temporary files (repo clones, build scratch, deploy render dirs). Defaults to the operating system temp directory. Set it to a path on a volume with free space when the default temp filesystem is small.