All Environment Variables

Alphabetical reference of Pilot’s environment variables. For grouped explanations with examples, see Configuration.

Core

Variable	Default	Description
`KAFKA_AUTO_OFFSET_RESET`	`latest`	No effect; kept for compatibility
`KAFKA_BOOTSTRAP_SERVERS`	`localhost:9092`	Kafka broker addresses (comma-separated)
`LOG_LEVEL`	`INFO`	Log level: `DEBUG`, `INFO` or `WARN` (case-insensitive). Any other value uses `INFO`
`METADATA_UPDATE_INTERVAL`	`10s`	Metadata collection frequency
`PORT`	`8080`	HTTP server port
`UI_PATH`	`./ui/dist`	Path to UI assets (overridden when embedded)

Server TLS

Variable	Default	Description
`SERVER_TLS_CERT_FILE`	`""`	Path to TLS certificate file (PEM)
`SERVER_TLS_ENABLED`	`false`	Enable HTTPS for the Pilot HTTP server
`SERVER_TLS_KEY_FILE`	`""`	Path to TLS private key file (PEM)
`SERVER_TLS_MIN_VERSION`	`1.2`	Minimum TLS version: `1.2` or `1.3`

Kafka Security

Variable	Default	Description
`KAFKA_SASL_KERBEROS_CONFIG_FILE`	`""`	Path to Kerberos config file (krb5.conf)
`KAFKA_SASL_KERBEROS_KEYTAB_FILE`	`""`	Path to Kerberos keytab file
`KAFKA_SASL_KERBEROS_PASSWORD`	`""`	Kerberos password (if not using keytab)
`KAFKA_SASL_KERBEROS_REALM`	`""`	Kerberos realm
`KAFKA_SASL_KERBEROS_SERVICE_NAME`	`kafka`	Kerberos service name
`KAFKA_SASL_KERBEROS_USERNAME`	`""`	Kerberos principal name
`KAFKA_SASL_MECHANISM`	`PLAIN`	SASL mechanism: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`, `GSSAPI`, `OAUTHBEARER`
`KAFKA_SASL_OAUTH_CLIENT_ID`	`""`	OAuth client ID
`KAFKA_SASL_OAUTH_CLIENT_SECRET`	`""`	OAuth client secret
`KAFKA_SASL_OAUTH_EXTENSIONS`	`""`	SASL `OAUTHBEARER` extensions sent to the brokers (comma-separated `key=value`); not sent to the token endpoint
`KAFKA_SASL_OAUTH_SCOPE`	`""`	OAuth scope
`KAFKA_SASL_OAUTH_TOKEN_ENDPOINT_URL`	`""`	OAuth token endpoint URL
`KAFKA_SASL_PASSWORD`	`""`	SASL password (PLAIN/SCRAM)
`KAFKA_SASL_USERNAME`	`""`	SASL username (PLAIN/SCRAM)
`KAFKA_SECURITY_PROTOCOL`	`PLAINTEXT`	Security protocol: `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, `SASL_SSL`
`KAFKA_SSL_CA_CERT_FILE`	`""`	Path to CA certificate file. Trusted for broker TLS and, with `OAUTHBEARER`, for the HTTPS token endpoint (in addition to the system roots)
`KAFKA_SSL_CA_CERT_PEM`	`""`	CA certificate PEM content (inline). Same trust scope as `KAFKA_SSL_CA_CERT_FILE`
`KAFKA_SSL_CERT_FILE`	`""`	Path to the client certificate (PEM, chain allowed) for mutual TLS. Needs a key via `KAFKA_SSL_KEY_FILE` or `KAFKA_SSL_KEY_PEM`. See Mutual TLS
`KAFKA_SSL_CERT_PEM`	`""`	Client certificate PEM content (inline). Used instead of `KAFKA_SSL_CERT_FILE` when both are set
`KAFKA_SSL_ENABLED_PROTOCOLS`	`TLSv1.2,TLSv1.3`	Not applied. The Kafka client uses TLS 1.2 or 1.3
`KAFKA_SSL_INSECURE_SKIP_VERIFY`	`false`	Skip TLS certificate verification for brokers and the `OAUTHBEARER` token endpoint (insecure)
`KAFKA_SSL_KEY_FILE`	`""`	Path to the client private key (PEM: PKCS#1, PKCS#8, EC, or PKCS#8 encrypted) for mutual TLS. Needs a certificate via `KAFKA_SSL_CERT_FILE` or `KAFKA_SSL_CERT_PEM`
`KAFKA_SSL_KEY_PASSWORD`	`""`	Password of a PKCS#8 encrypted client key (`BEGIN ENCRYPTED PRIVATE KEY`). Ignored, with a warning, when the key is not encrypted
`KAFKA_SSL_KEY_PEM`	`""`	Client private key PEM content (inline). Used instead of `KAFKA_SSL_KEY_FILE` when both are set
`KAFKA_SSL_VERIFY_HOSTNAME`	`true`	Verify broker hostname against certificate. `false` skips only the hostname match; the certificate chain is still verified

Balance Engine

Variable	Default	Description
`PILOT_BALANCE_FLOOR`	`""` (off)	Optional minimum difference. Set, for example, `bytes=2MB/s disk=2GiB` to ignore smaller per-broker differences on quiet test clusters: a rate or disk metric is then balanced only when some broker is at least that far from its equal share. Settings left out use `bytes=2MB/s` and `disk=2GiB`; message rates follow the byte rate at the average message size unless `msgs=` is given (`msgs=auto` is accepted). Leader and follower counts are not affected. Unset or `off` balances differences of any size. An invalid value stops Pilot at startup. See Minimum Difference
`PILOT_BALANCE_MIN_RF`	`0`	Minimum replication factor enforcement (0 = disabled)
`PILOT_BALANCE_RACK_AWARE`	`true`	Enforce rack-aware partition placement
`PILOT_BALANCE_THRESHOLD`	`5.0`	Applies per broker and load: Pilot moves partitions only when a broker stays more than twice this percentage from its fair share (10% at the default), then evens that load until every broker is within this percentage, give or take one partition. Must be greater than 0. See Even Balance
`PILOT_BALANCE_WORKERS`	`0`	Candidate-generation goroutines (0 = auto, uses `GOMAXPROCS`); does not affect proposal output
`PILOT_BROKER_PROFILE`	`""`	Broker capacity, e.g. `network=10Gbit/s disk=2TiB`, plus optional `rack=`, `host=` or `broker=` selector rules separated by `;`. Reports broker network and disk utilization and does not change balancing; fair shares do not depend on it, and capacity-based overload protection is planned. With `network=` set, settling after moves ends on evidence instead of a timer. An invalid value stops Pilot at startup. See Broker Profiles
`PILOT_BROKER_PROFILE_FILE`	`""`	Path to a broker profile file (same rules, one per line, `#` comments). Set only one of `PILOT_BROKER_PROFILE` and `PILOT_BROKER_PROFILE_FILE`

Movement Control

Variable	Default	Description
`PILOT_MOVE_MAX_PER_BROKER`	`20`	Max concurrent moves per broker
`PILOT_PROPOSAL_MAX_PARTITIONS`	`0`	Max partitions a single proposal may move (0 = unlimited). Whole transitions with the lowest marginal benefit per movement cost are dropped first, then the remaining benefit is checked again. Critical/RF-fix moves are always kept

Throttle

Variable	Default	Description
`PILOT_THROTTLE_MANAGED`	`true`	Pilot manages replication throttles. `false` marks proposals unsafe to apply (`throttles_externally_managed`) and skips the startup cleanup of leftover throttles
`PILOT_THROTTLE_MAX_RATE_MB`	`1000`	Highest throttle that can be set at runtime, in MB/s. Must not be below `PILOT_THROTTLE_RATE_MB`
`PILOT_THROTTLE_RATE_MB`	`50`	Base throttle rate in MB/s. Must be >= 1 when `PILOT_THROTTLE_MANAGED=true` (0 or negative is rejected at startup)

Self-Healing

Variable	Default	Description
`PILOT_HEAL_CRITICAL_ENABLED`	`false`	Enable critical fixes healing (URP, rack)
`PILOT_HEAL_CRITICAL_INTERVAL`	`5m`	Critical healing check interval
`PILOT_HEAL_DRY_RUN`	`true`	Simulate healing without applying changes
`PILOT_HEAL_ENABLED`	`false`	Enable activity-based healing
`PILOT_HEAL_INTERVAL`	`30m`	Activity healing interval
`PILOT_HEAL_MAX_PARTITIONS_PER_RUN`	`0`	Max partitions moved per healing cycle (`0` = unlimited)
`PILOT_HEAL_RF_ENABLED`	`false`	Enable replication factor increase healing
`PILOT_HEAL_RF_INTERVAL`	`15m`	RF healing check interval
`PILOT_HEAL_WINDOW_END`	`-1`	Healing window end hour (0-23, -1 = always)
`PILOT_HEAL_WINDOW_START`	`-1`	Healing window start hour (0-23, -1 = always)

Exclusions & Observability

Variable	Default	Description
`PILOT_BROKER_EXPIRY`	`1h`	How long a broker must stay continuously unavailable and unreferenced by any partition replica set before Pilot forgets it. Removes it from the tracked broker union and tombstones its persisted state so a permanently scaled-down broker stops inflating `TotalBrokers` and blocking rolling restarts. Set to `0` to disable. A broker that reappears in metadata is tracked again.
`PILOT_EXCLUDE_TOPICS`	`""`	Comma-separated topic regexes to leave out of proposals and self-healing (unanchored)
`PILOT_FOLLOWER_LAG_WARNING_THRESHOLD`	`1000`	Warning threshold for total follower lag. When total cluster follower lag exceeds this value, the health endpoint reports a warning.

Consumer Groups

Variable	Default	Description
`PILOT_CONSUMER_GROUP_COLLECTION_ENABLED`	`true`	Enable background consumer group collection
`PILOT_CONSUMER_GROUP_COLLECTION_INTERVAL`	`15s`	Collection interval

CORS

Variable	Default	Description
`CORS_ALLOWED_ORIGINS`	`*`	Allowed origins (comma-separated)
`CORS_ALLOWED_METHODS`	`GET,POST,PUT,DELETE,OPTIONS`	Allowed methods (comma-separated)
`CORS_ALLOWED_HEADERS`	`*`	Allowed request headers (comma-separated)
`CORS_EXPOSED_HEADERS`	`""`	Response headers exposed to the browser (comma-separated)
`CORS_ALLOW_CREDENTIALS`	`false`	Allow credentials on cross-origin requests
`CORS_MAX_AGE`	`0`	Preflight cache duration in seconds

An empty list means *.

Pilot Agent

Variable	Default	Description
`PILOT_AGENT_BOOTSTRAP_TOKEN`	required	Master token for agent certificate enrollment. Required when using auto-TLS. Generate with `openssl rand -hex 32`
`PILOT_AGENT_DATA_DIR`	`/data/agent-certs`	Directory for auto-generated CA and certificates
`PILOT_AGENT_ENABLED`	`false`	Enable the agent gRPC server
`PILOT_AGENT_GRPC_PORT`	`9190`	Port for agent gRPC connections
`PILOT_AGENT_INSECURE`	`false`	Allow gRPC server without TLS (development only)
`PILOT_AGENT_TLS_CA`	(auto)	Path to CA certificate for verifying agents
`PILOT_AGENT_TLS_CERT`	(auto)	Path to server TLS certificate
`PILOT_AGENT_TLS_KEY`	(auto)	Path to server TLS private key
`PILOT_AGENT_TLS_SANS`	`""`	Extra DNS names or IP addresses for auto-generated server certificate (comma-separated)
`PILOT_DEPLOY_ALLOW_HTTP`	`false`	Allow SSH deploy endpoints over plain HTTP. By default, deploy endpoints that transmit SSH credentials require HTTPS
`PILOT_TRUSTED_PROXIES`	`""` (trust all)	Comma- or space-separated CIDRs or IPs of reverse proxies whose `X-Forwarded-Proto` and `X-Forwarded-Host` Pilot trusts, for the HTTPS check on SSH deploy endpoints and the URLs given to agents. Unset trusts every source; set it when clients can reach Pilot without the proxy. Invalid entries are skipped with a warning
`PILOT_AGENT_DOWNLOAD_URL`	`https://downloads.calinora.io/agent/v{version}/pilot-agent-linux-{arch}`	Upstream URL template for downloading agent binaries. Supports `{version}` and `{arch}` placeholders. Override for corporate proxies (JFrog, Nexus)
`PILOT_AGENT_BINARY_DIR`	`""`	Local directory for air-gapped mode. When set, Pilot reads agent binaries from this directory and does not download from the upstream URL
`PILOT_AGENT_BINARY_CACHE_DIR`	`{data-dir}/binaries`	Directory where downloaded agent binaries are cached on disk
`PILOT_AGENT_SSH_KNOWN_FINGERPRINTS`	`""`	Comma-separated list of trusted SSH host-key fingerprints in canonical OpenSSH form (`SHA256:<base64>`). Pilot merges this list into every hop of an agent deploy that does not supply its own `knownFingerprints`. Deploys without any trust source (fingerprint, captured host key, or explicit `allowInsecureHostKey`) are refused. See agent SSH host key verification

Pilot Agent (Agent-Side)

These variables configure the agent binary deployed alongside each Kafka broker. They are set on the agent, not on the Pilot server.

Variable	Default	Description
`AGENT_BOOTSTRAP_TOKEN`	`""`	Token for certificate enrollment (master token or single-use enrollment token)
`AGENT_BOOTSTRAP_URL`	`""`	URL for certificate bootstrapping (e.g., `http://pilot:8080/api/v1/agents/bootstrap-cert`)
`AGENT_BROKER_ID`	`0`	Kafka broker ID. Auto-detected from `server.properties` or `meta.properties` if not set
`AGENT_CA`	`""`	Path to CA certificate for server verification
`AGENT_CERT`	`""`	Path to mTLS client certificate
`AGENT_INSECURE`	`false`	Allow running without TLS (development only)
`AGENT_KEY`	`""`	Path to mTLS client private key
`AGENT_LOG_DIRS`	`""`	Kafka log directories (comma-separated). Auto-detected from the running broker process if not set
`AGENT_NODE_ID`	(hostname)	Node identifier (defaults to system hostname)
`AGENT_SERVER`	`""`	Pilot gRPC server address (e.g., `pilot:9190`)
`AGENT_KAFKA_SERVICE_UNIT`	`""`	Override systemd unit name for broker lifecycle commands (e.g., `my-kafka.service`)
`AGENT_KAFKA_START_CMD`	`""`	Override broker start command
`AGENT_KAFKA_STOP_CMD`	`""`	Override broker stop command
`AGENT_ALLOW_RESTART`	`true`	Permit restart/stop/start commands. Set to `false` to disable broker lifecycle management on this agent
`AGENT_DOCKER_CONTAINER`	`""`	Docker container name to manage for lifecycle operations (`docker stop/start/restart`). Required for containerized brokers when using `pid: "host"`

MCP Server

Variable	Default	Description
`PILOT_MCP_ENABLED`	`true`	Enable Model Context Protocol server

AI Chat

Variable	Default	Description
`PILOT_CHAT_API_KEY`	`""`	API key for chat provider (required if chat enabled)
`PILOT_CHAT_APPROVAL_TIMEOUT`	`5m`	User approval window for mutations
`PILOT_CHAT_BASE_URL`	`""`	Override API base URL. Azure OpenAI: `https://<resource>.openai.azure.com/openai` (trailing `/openai` required)
`PILOT_CHAT_CONVERSATION_TTL`	`24h`	Conversation expiry time
`PILOT_CHAT_ENABLED`	`false`	Enable AI chat assistant
`PILOT_CHAT_MAX_CONTEXT_TOKENS`	`30000`	Estimated context-token budget per request (history + tool catalog); min 4096
`PILOT_CHAT_MAX_CONVERSATIONS`	`10`	Max conversations per user
`PILOT_CHAT_MAX_TOKENS`	`4096`	Max response tokens
`PILOT_CHAT_MAX_TOOL_RESULT_CHARS`	`8000`	Max characters of each tool result kept in conversation context; min 1000
`PILOT_CHAT_MODEL`	`claude-haiku-4-5-20251001`	AI model to use. For Azure OpenAI, the deployment name
`PILOT_CHAT_OPENAI_API`	`auto`	OpenAI only: `auto`, `responses`, or `chat_completions`. `auto` uses Responses for GPT-5/GPT-6 model names and Chat Completions otherwise
`PILOT_CHAT_PROVIDER`	`anthropic`	Chat provider: `anthropic` or `openai`
`PILOT_CHAT_RATE_LIMIT`	`20`	Messages per minute per user

The chat HTTP client honors the standard Go SSL_CERT_FILE / SSL_CERT_DIR variables; see AI Chat configuration for Azure OpenAI and corporate CA setup.

License

Variable	Default	Description
`LICENSE_FETCH_INTERVAL`	`1h`	Auto-fetch interval
`LICENSE_FETCH_SUBSCRIPTION_ID`	`""`	Subscription ID for auto-fetch
`LICENSE_FETCH_TOKEN`	`""`	Per-customer fetch token
`LICENSE_FETCH_URL`	`https://license.calinora.io/api/license/fetch`	License fetch endpoint
`LICENSE_STRING`	`""`	JWT license token

Audit Logging

Variable	Default	Description
`AUDIT_ENABLED`	`true`	Enable audit event logging
`AUDIT_PARTITIONS`	`1`	Audit topic partition count
`AUDIT_REPLICATION_FACTOR`	`0`	Audit topic replication factor for a new topic (0 uses the broker default; a default of 1 is raised to 3, or 2 on a two-broker cluster)
`AUDIT_RETENTION_MS`	`2592000000`	Audit topic retention in milliseconds (default 30 days)
`AUDIT_STORE_MAX_ITEMS`	`10000`	Max audit events kept in memory for the UI
`AUDIT_TOPIC`	`__pilot_audit_log`	Kafka topic name for audit events
`AUDIT_USER_ID_CLAIM`	`upn`	Identity recorded as `userId`: `upn` (default), `sub` or `email`. Other values fall back to upn, then sub, then email

Authentication (UI & API)

Global

Variable	Default	Description
`AUTH_COOKIE_DOMAIN`	`""`	Cookie domain scope
`AUTH_COOKIE_NAME`	`pilot_session`	Session cookie name
`AUTH_COOKIE_SECRET`	`""`	HMAC signing key (auto-generated in dev)
`AUTH_COOKIE_SECURE`	`true`	HTTPS-only cookies
`AUTH_DEBUG_EXPOSE_TOKENS`	`false`	Expose raw tokens in `/auth/me` (debug only)
`AUTH_SESSION_TTL`	`12h`	Session time-to-live

Per-Provider (AUTH_<PROVIDER>_*)

Replace <PROVIDER> with ENTRAID, GOOGLE, GITHUB, or OIDC. AUTH_<PROVIDER>_ENABLED must be present in the environment for the rest of a provider’s block to be read.

Variable	Default	Description
`AUTH_<PROVIDER>_ALLOWED_AUDIENCES`	`<client-id>`	Allowed token audiences (comma-separated), matched against a token’s `aud` and `azp`. Defaults to the client id (Entra ID also accepts `api://<client-id>`) so a bearer JWT must be minted for this deployment. A provider with no client id and no allowlist rejects every bearer JWT
`AUTH_<PROVIDER>_ALLOWED_DOMAINS`	`""`	Allowed email domains (comma-separated). Matched against the email resolved via `AUTH_<PROVIDER>_EMAIL_CLAIM`
`AUTH_<PROVIDER>_ALLOWED_GROUPS`	`""`	Allowed groups (comma-separated). Matched against the groups resolved via `AUTH_<PROVIDER>_GROUPS_CLAIM`
`AUTH_<PROVIDER>_ALLOWED_ORGANIZATIONS`	`""`	Allowed organizations (comma-separated)
`AUTH_<PROVIDER>_ALLOW_SIGN_UP`	`true`	Allow new user registration
`AUTH_<PROVIDER>_API_URL`	`""`	Userinfo endpoint URL
`AUTH_<PROVIDER>_AUTH_URL`	`""`	OAuth authorization URL
`AUTH_<PROVIDER>_AUTO_LOGIN`	`false`	Auto-redirect to provider login
`AUTH_<PROVIDER>_CLIENT_ID`	`""`	OAuth client ID
`AUTH_<PROVIDER>_CLIENT_SECRET`	`""`	OAuth client secret
`AUTH_<PROVIDER>_EMAIL_CLAIM`	`""`	Claim used for the session email and `ALLOWED_DOMAINS`. Consulted first when set; default chain `email`, `preferred_username`, `upn` is the fallback
`AUTH_<PROVIDER>_ENABLED`	`false`	Enable this provider
`AUTH_<PROVIDER>_GROUPS_CLAIM`	`""`	Claim used for session groups and `ALLOWED_GROUPS`. Consulted first when set; default chain `groups`, `roles`, `role`, `group` is the fallback (first present non-empty key wins). Accepts an array or a single string. AD FS: `roles`
`AUTH_<PROVIDER>_ISSUER`	`""`	OIDC issuer. Trust anchor for bearer JWT and `id_token` verification; required for local signature checking. A trailing slash is ignored when matching a token’s `iss`
`AUTH_<PROVIDER>_JWKS_CACHE_TTL`	`15m`	How long fetched signing keys are cached
`AUTH_<PROVIDER>_JWKS_URL`	`""`	JWKS endpoint. Overrides discovery from the issuer (still requires `AUTH_<PROVIDER>_ISSUER`). Must be an absolute `http`/`https` URL; anything else is ignored
`AUTH_<PROVIDER>_NAME`	Auto	Display name
`AUTH_<PROVIDER>_SCOPES`	`openid email profile`	OAuth scopes
`AUTH_<PROVIDER>_TOKEN_URL`	`""`	OAuth token URL
`AUTH_<PROVIDER>_USERNAME_CLAIM`	`""`	Claim used for the session username (UPN). Consulted first when set; default chain `upn`, `preferred_username` is the fallback. AD FS: `upn`
`AUTH_<PROVIDER>_USE_PKCE`	`true`	Enable PKCE
`AUTH_<PROVIDER>_USE_REFRESH_TOKEN`	`true`	Enable refresh tokens

Personal Access Tokens

Variable	Default	Description
`AUTH_PAT_ENABLED`	`false`	Enable PAT creation and validation (requires auth and `AUTH_PAT_HASH_SECRET`)
`AUTH_PAT_HASH_SECRET`	`""`	Required for PATs. HMAC-SHA256 secret for token hashing. Must be stable and persistent.
`AUTH_PAT_MAX_PER_USER`	`10`	Maximum tokens per user

Entra ID Convenience

Variable	Default	Description
`AUTH_ENTRAID_TENANT`	`""`	Azure tenant ID (auto-derives auth/token/issuer URLs)