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. With Ollama, the docs index uses BYTECHEF_AI_PROVIDER_OLLAMA_URL and the optional BYTECHEF_AI_PROVIDER_OLLAMA_API_KEY (sensitive)
Coming soon. Auto Memory 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_AUTO_MEMORY_PROVIDER
Where AI agent Auto Memory entries are stored (jdbc, filesystem, aws). filesystem and aws use the configured file storage; aws requires the Enterprise Edition AWS file-storage module, and selecting a file-backed provider whose storage is not configured fails at startup. The JDBC store is used when unset
Where AI agent chat memory is stored (in_memory, jdbc, redis, aws). BYTECHEF_DATABASE=h2 defaults this to in_memory because the spring_ai_chat_memory table used by the Chat Memory component is created only on PostgreSQL; the session tables of Chat Memory v2 (ai_session, ai_session_event) are created on both PostgreSQL and H2
jdbc (in_memory on H2)
BYTECHEF_AI_MEMORY_AWS_ACCESS_KEY_ID
AWS access key ID of the S3 client used when the provider is aws (sensitive). Must be set together with BYTECHEF_AI_MEMORY_AWS_SECRET_ACCESS_KEY; when both are unset, BYTECHEF_CLOUD_AWS_ACCESS_KEY_ID/BYTECHEF_CLOUD_AWS_SECRET_ACCESS_KEY are used, and when those are unset too, the AWS default credentials provider chain
-
BYTECHEF_AI_MEMORY_AWS_BUCKET_PREFIX
Prefix of the per-tenant S3 bucket (<prefix>-<tenantId>) that stores chat memory when the provider is aws. S3 bucket names are global, so pick a prefix no other AWS account uses
bytechef-chat-memory
BYTECHEF_AI_MEMORY_AWS_KEY_PREFIX
Key prefix prepended to every object Chat Memory v1 and v2 store in S3 when the provider is aws
-
BYTECHEF_AI_MEMORY_AWS_REGION
AWS region of the S3 client used when the provider is aws. Falls back to BYTECHEF_CLOUD_AWS_REGION, then to the AWS default region provider chain
-
BYTECHEF_AI_MEMORY_AWS_SECRET_ACCESS_KEY
AWS secret access key of the S3 client used when the provider is aws (sensitive). Must be set together with BYTECHEF_AI_MEMORY_AWS_ACCESS_KEY_ID; see that variable for the fallback
-
BYTECHEF_AI_MEMORY_AWS_SESSION_BUCKET_PREFIX
Prefix of the per-tenant S3 bucket that Chat Memory v2 uses when the provider is aws. The bucket is named <prefix>-<tenantId>; when that is not a valid S3 bucket name, it is sanitized (lowercased, invalid characters replaced with hyphens, shortened if too long) and suffixed with a hash. S3 bucket names are global, so pick a prefix no other AWS account uses
bytechef-session
BYTECHEF_AI_MEMORY_REDIS_HOST
Redis server hostname used when the provider is redis
localhost
BYTECHEF_AI_MEMORY_REDIS_PORT
Redis server port used when the provider is redis
6379
BYTECHEF_AI_MEMORY_REDIS_USERNAME
Redis ACL username used when the provider is redis; requires BYTECHEF_AI_MEMORY_REDIS_PASSWORD
-
BYTECHEF_AI_MEMORY_REDIS_PASSWORD
Redis password used when the provider is redis (sensitive)
-
BYTECHEF_AI_MEMORY_REDIS_SESSION_KEY_PREFIX
Key prefix of Chat Memory v2 when the provider is redis; its keys start with <prefix><tenantId>:
bytechef-session:
BYTECHEF_AI_MEMORY_SESSION_MAX_ARCHIVED_EVENTS
Maximum number of archived (compacted-away) events Chat Memory v2 keeps per session when the provider is redis or aws; older archived events are deleted
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.
Upper bound on concurrent tasks on the default async executor, which carries mail, notifications and other background work. There is no queue: a submitter waits for a permit. Workflow task and trigger execution are bounded separately by the worker variables below
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
Set to h2 to run on an embedded H2 file database under ~/.bytechef, with no PostgreSQL server. Evaluation and local development only; leave unset for PostgreSQL.
-
BYTECHEF_DATASOURCE_URL
Database URL
-
BYTECHEF_DATASOURCE_USERNAME
Database username (sensitive)
-
BYTECHEF_DATASOURCE_PASSWORD
Database password (sensitive)
-
BYTECHEF_DATASOURCE_MAXIMUM_POOL_SIZE
Maximum JDBC connections in the pool. Shared by Quartz's 10 job-store threads, workflow task execution and request threads, so it must stay comfortably above Quartz's thread count on its own
30
BYTECHEF_DATABASE=h2 supplies the datasource itself, so the three BYTECHEF_DATASOURCE_*
variables are unnecessary alongside it. See
Local Docker for what H2 does and
does not support.
Comma-separated origins (scheme, host and optional port, no path or wildcard, e.g. https://app.example.com,https://admin.example.com) of the applications allowed to embed the Automation Hub, Workflow Builder and Integration Marketplace pages. It is sent as Content-Security-Policy: frame-ancestors on those pages, and the pages accept their initialization message only from these origins. When empty, any origin can embed the pages and the pages log a warning in the browser console. EE only
Encryption provider (FILESYSTEM, PROPERTY). FILESYSTEM generates a key on first start and keeps it in ~/.bytechef/key (/root/.bytechef/key in the Docker image). In a container, bind-mount ~/.bytechef to the host, or the key is lost when the container is re-created and stored credentials can no longer be decrypted. Use PROPERTY for multiple replicas or ephemeral disks.
FILESYSTEM
BYTECHEF_ENCRYPTION_PROPERTY_KEY
Encryption key (sensitive). Required when BYTECHEF_ENCRYPTION_PROVIDER=PROPERTY; use the same stable value on every instance.
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.
Remember Me key (sensitive). Generated on first start and kept in ~/.bytechef/remember-me-key when unset. Set it explicitly across replicas, or a remember-me cookie signed by one is rejected by the others.
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.
Sign OTel log export requests with AWS Signature Version 4 for the CloudWatch OTLP endpoint (https://logs.<region>.amazonaws.com/v1/logs). Credentials come from the AWS SDK default provider chain. See Observability.
false
BYTECHEF_OBSERVABILITY_LOGGING_AWS_LOG_GROUP
Existing CloudWatch log group the logs are written to, sent as the x-aws-log-group header. Required when signing is enabled unless the header is set through management.opentelemetry.logging.export.otlp.headers.
-
BYTECHEF_OBSERVABILITY_LOGGING_AWS_LOG_STREAM
Existing CloudWatch log stream the logs are written to, sent as the x-aws-log-stream header. Required when signing is enabled unless the header is set through management.opentelemetry.logging.export.otlp.headers.
-
BYTECHEF_OBSERVABILITY_LOGGING_AWS_REGION
AWS region used in the signature scope. Derived from a logs.<region>.amazonaws.com endpoint host when unset; required for any other host.
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, and the cap on concurrent task execution process-wide. On a single-node deployment this is simply "max concurrent workflow tasks"
10
BYTECHEF_WORKER_TASK_SYNC_CONCURRENCY_LIMIT
Concurrent executions allowed in the synchronous, interactive lane - the API Platform sync request path and the workflow editor's Test button. Kept separate from the queue above so a burst of scheduled runs cannot leave an interactive caller waiting
5
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
