--- title: "All Environment Variables - Pilot Docs" description: "Alphabetical reference of Pilot environment variables" url: "https://docs.calinora.io/reference/environment-variables/" --- # All Environment Variables Alphabetical reference of Pilot’s environment variables. For grouped explanations with examples, see [Configuration](https://docs.calinora.io/configuration/environment-variables/). ## 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](https://docs.calinora.io/configuration/tls/#mutual-tls-mtls) | | `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](https://docs.calinora.io/features/proposals/#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](https://docs.calinora.io/features/proposals/#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](https://docs.calinora.io/features/proposals/#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:`). 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](https://docs.calinora.io/features/agents/#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://.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](https://docs.calinora.io/configuration/environment-variables/#ai-chat) 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\_\\_\*) Replace `` with `ENTRAID`, `GOOGLE`, `GITHUB`, or `OIDC`. `AUTH__ENABLED` must be present in the environment for the rest of a provider’s block to be read. | Variable | Default | Description | | - | - | - | | `AUTH__ALLOWED_AUDIENCES` | `` | Allowed token audiences (comma-separated), matched against a token’s `aud` and `azp`. Defaults to the client id (Entra ID also accepts `api://`) so a bearer JWT must be minted for this deployment. A provider with no client id and no allowlist rejects every bearer JWT | | `AUTH__ALLOWED_DOMAINS` | `""` | Allowed email domains (comma-separated). Matched against the email resolved via `AUTH__EMAIL_CLAIM` | | `AUTH__ALLOWED_GROUPS` | `""` | Allowed groups (comma-separated). Matched against the groups resolved via `AUTH__GROUPS_CLAIM` | | `AUTH__ALLOWED_ORGANIZATIONS` | `""` | Allowed organizations (comma-separated) | | `AUTH__ALLOW_SIGN_UP` | `true` | Allow new user registration | | `AUTH__API_URL` | `""` | Userinfo endpoint URL | | `AUTH__AUTH_URL` | `""` | OAuth authorization URL | | `AUTH__AUTO_LOGIN` | `false` | Auto-redirect to provider login | | `AUTH__CLIENT_ID` | `""` | OAuth client ID | | `AUTH__CLIENT_SECRET` | `""` | OAuth client secret | | `AUTH__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__ENABLED` | `false` | Enable this provider | | `AUTH__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__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__JWKS_CACHE_TTL` | `15m` | How long fetched signing keys are cached | | `AUTH__JWKS_URL` | `""` | JWKS endpoint. Overrides discovery from the issuer (still requires `AUTH__ISSUER`). Must be an absolute `http`/`https` URL; anything else is ignored | | `AUTH__NAME` | Auto | Display name | | `AUTH__SCOPES` | `openid email profile` | OAuth scopes | | `AUTH__TOKEN_URL` | `""` | OAuth token URL | | `AUTH__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__USE_PKCE` | `true` | Enable PKCE | | `AUTH__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) |