Configuration options for ByteChef through environment variables
ByteChef can be configured using environment variables. This page documents all available environment variables, organized by category.
Every name below is the property path uppercased with dots and dashes replaced by underscores — bytechef.ai.provider.open-ai.api-key becomes BYTECHEF_AI_PROVIDER_OPEN_AI_API_KEY. Dropping the underscore that stands for a dash (..._OPENAI_API_KEY) produces a name that binds to nothing: as an environment variable it is silently ignored, and the same key in a YAML file fails the boot, because bytechef.* binds with ignoreUnknownFields = false.
Coming soon. The AI Copilot is on the upcoming release track and is not yet available in the latest released version of ByteChef.
Environment Variable
Description
Default Value
BYTECHEF_AI_COPILOT_ENABLED
Enable or disable the AI copilot feature
false
BYTECHEF_AI_COPILOT_PROVIDER
Chat-model provider to prefer for Copilot — accepts the short provider name (e.g. anthropic, openAi) or the full catalog key (e.g. ai.provider.anthropic), case-insensitively; unrecognized values fall back to auto-detection. In CE it overrides auto-detection from the configured provider API keys/endpoints. In EE it is used as the environment default provider when set, provided that provider is enabled and has a configured chat model (BYTECHEF_AI_PROVIDER_CHAT_<PROVIDER>_OPTIONS_MODEL); otherwise Copilot falls back to the first enabled chat provider. A per-turn model picked in the Copilot toolbar always overrides this.
-
BYTECHEF_AI_COPILOT_EMBEDDING_PROVIDER
Embedding provider for the Copilot vector index (OLLAMA, OPENAI)
-
BYTECHEF_AI_COPILOT_EMBEDDING_API_KEY
API key for the Copilot embedding provider — OpenAI only; Ollama runs locally and needs none (sensitive)
Enable or disable product analytics (PostHog). false in the base configuration, but the prod profile — which the published container image activates — sets it to true, so a self-hosted container has analytics on unless you set this explicitly.
Enable uploading of Java (jar) custom components. When disabled, Java custom component uploads are rejected while other languages (JavaScript, Python, Ruby) and previously uploaded Java custom components continue to work. Coming soon — upcoming release
true
BYTECHEF_COMPONENT_CUSTOM_COMPONENT_JAVA_LOADER
Loader used to run Java custom components (CLASS_LOADER, ESPRESSO). ESPRESSO executes Java custom components inside a sandboxed GraalVM Espresso guest JVM instead of an in-process classloader. Coming soon — upcoming release
Base URL of the ByteChef GitHub proxy used to fetch pre-built workflow templates. Point it at a private mirror when the instance cannot reach the public proxy. Note: this property is top-level (github-proxy.baseUrl), not under the bytechef.* prefix.
Client secret for predefined OAuth2 app (sensitive)
-
BYTECHEF_OAUTH2_AUTHORIZATION_SERVER_ENABLED
Enable the embedded OAuth2 authorization server. When disabled, the authorization server endpoints and the OAuth2 resource-server support on the MCP endpoints are not exposed
false
BYTECHEF_OAUTH2_RESOURCE_SERVER_ISSUERS_0_URI
Issuer identifier (iss claim / issuer URI) whose JWTs are trusted on the MCP endpoints. Repeat with _1_, _2_, … for additional issuers
JWT claim (e.g. groups, roles) whose values are mapped to granted authorities. When unset, authorities are resolved from the ByteChef user identified by sub
Authority granted to every token from this issuer, in addition to any mapped from the authorities claim
-
BYTECHEF_OAUTH2_RESOURCE_SERVER_ISSUERS_0_SELF
Whether this issuer is the ByteChef embedded authorization server; when true, audience validation enforces that a token's aud contains the requested MCP endpoint URL
For an external issuer, the fixed audience value its tokens must carry. When unset, audience validation is skipped for this issuer
-
Coming soon. The BYTECHEF_OAUTH2_AUTHORIZATION_SERVER_* and BYTECHEF_OAUTH2_RESOURCE_SERVER_* variables are on the upcoming release track and are not yet available in the latest released version of ByteChef.
Coming soon. Plan-limit enforcement (tiers, rate limiting, concurrency slots, cost caps, and the quota variables below) is on the upcoming release track and is not yet available in the latest released version of ByteChef.
Environment Variable
Description
Default Value
BYTECHEF_PLAN_TIER
Plan tier whose limits apply to the deployment (SELF_HOSTED, FREE, PRO, TEAM, ENTERPRISE). SELF_HOSTED leaves every limit unset — the pre-plan unlimited behavior
SELF_HOSTED
BYTECHEF_PLAN_ENFORCEMENT_ENABLED
Enable plan-limit enforcement (rate limits, concurrency slots, cost cap, quotas). With the SELF_HOSTED tier every limit is null, so enforcement is a no-op until a tier is configured
true
BYTECHEF_PLAN_ENFORCEMENT_PROVIDER
Backing store for rate buckets and concurrency counters (local, redis). local keeps per-node in-memory state; redis shares state across nodes for strict global limits and fails open on Redis outages
local
BYTECHEF_PLAN_LIMITS_INCLUDED_MONTHLY_COST_USD
Override: execution spend (USD) allowed per calendar month (UTC) before new asynchronous runs are rejected
tier default
BYTECHEF_PLAN_LIMITS_SYNC_REQUESTS_PER_MINUTE
Override: sustained per-minute rate for synchronous workflow executions (webhook trigger calls plus the MCP and A2A secret-key endpoints)
tier default
BYTECHEF_PLAN_LIMITS_ASYNC_REQUESTS_PER_MINUTE
Override: sustained per-minute rate for asynchronous workflow submissions
tier default
BYTECHEF_PLAN_LIMITS_API_REQUESTS_PER_MINUTE
Override: sustained per-minute rate for general public API requests
tier default
BYTECHEF_PLAN_LIMITS_BURST_MULTIPLIER
Override: token-bucket burst capacity as a multiple of the sustained rate
tier default
BYTECHEF_PLAN_LIMITS_MAX_CONCURRENT_EXECUTIONS
Override: concurrent execution slots per tenant
tier default
BYTECHEF_PLAN_LIMITS_SYNC_RUN_TIMEOUT
Override: wall-clock limit for a synchronous run (ISO-8601 duration, e.g. PT2M). Caps the webhook sync wait; it can only tighten the built-in default, never extend it
tier default
BYTECHEF_PLAN_LIMITS_ASYNC_RUN_TIMEOUT
Override: wall-clock limit for an asynchronous run (ISO-8601 duration). Enforced by the job timeout monitor
tier default
BYTECHEF_PLAN_LIMITS_MAX_WORKSPACES
Override: number of workspaces the tenant may create
tier default
BYTECHEF_PLAN_LIMITS_MAX_STORAGE_BYTES
Override: total asset-file storage bytes across the tenant
tier default
BYTECHEF_PLAN_LIMITS_LOG_RETENTION_DAYS
Override: execution history retention window in days; older finished runs are purged by the retention monitor
tier default
BYTECHEF_PLAN_LIMITS_MAX_MEMBERS
Override: number of member accounts (pending invitations count)
tier default
Rejections increment the bytechef_plan_limit_rejection counter (tag limit =
login, sync, api, preauth, resume, async, concurrency, cost, timeout,
workspace, member or storage) when observability is enabled. Rate and cost rejections return HTTP 429
with Retry-After; quota rejections (workspaces, members, storage) return HTTP 403 — a capacity
ceiling is not retryable.
Enable Single Sign-On via an external identity provider (SAML 2.0 / OIDC). Enterprise Edition only; Community Edition supports local login and social login
System administrator is used for accessing protected data reachable through /actuator/** endpoints. For example /actuator/env returns all environment properties.
Run database upgrades (Liquibase migrations) at startup. Disable on read-only replicas or when only a designated instance should apply schema changes in a multi-instance deployment.
Enable or disable user guiding (in-application tutorials). false in the base configuration; the prod profile used by the published container image sets it to true.
Default timeout for task execution in milliseconds. Unset falls back to the built-in 24-hour ceiling; a task's own timeout parameter overrides both.
- (24 hours)
BYTECHEF_WORKER_TASK_SUBSCRIPTIONS_DEFAULT
Number of concurrent consumers for the default worker queue
10
BYTECHEF_WORKER_TASK_SUBSCRIPTIONS_<QUEUE_NAME>
Number of concurrent consumers for an additional worker queue (e.g., captions for tasks routed via node: captions). The queue must be created before tasks can be routed to it; ByteChef creates the queue automatically when the worker bootstraps if it doesn't already exist.
Coming soon. The execution recovery, timeout, and retention monitors (the variables in this and the following two subsections) are on the upcoming release track and are not yet available in the latest released version of ByteChef.
Environment Variable
Description
Default Value
BYTECHEF_WORKFLOW_EXECUTION_RECOVERY_ENABLED
Enable the orphaned-job recovery monitor. Workers heartbeat every in-flight task every 30 seconds; a job whose row and non-terminal task executions all go stale is marked FAILED and becomes resumable
Enable the per-run timeout monitor, which fails STARTED jobs whose runtime exceeds the plan's async run timeout or the default below. Timed-out runs are not auto-resumed
Enable the retention monitor, which permanently deletes finished jobs (including their task executions and contexts) older than the plan's log retention window or the default below
Enable uploading of Java (jar) code workflows. When disabled, Java code workflow uploads are rejected while other languages (JavaScript, Python, Ruby) and previously uploaded Java code workflows continue to work. Coming soon — upcoming release
true
BYTECHEF_WORKFLOW_CODE_WORKFLOW_JAVA_LOADER
Loader used to run Java code workflows (CLASS_LOADER, ESPRESSO). ESPRESSO executes Java code workflows inside a sandboxed GraalVM Espresso guest JVM instead of an in-process classloader. Coming soon — upcoming release
