Skip to main content
This page provides a comprehensive reference of all environment variables used by the Kubiya CLI and workers.

Quick Reference

Authentication

Configure API keys and Control Plane access

Worker Configuration

Worker behavior and resource limits

Logging & Debug

Control logging verbosity and debug output

Performance

Tune concurrency and timeouts

Authentication Variables

KUBIYA_API_KEY

KUBIYA_API_KEY
string
required
API authentication key for accessing the Kubiya Control Plane.
Notes:
  • Required for all CLI operations
  • Must start with kby_ prefix
  • Get from Composer UI or API
  • Keep secure and rotate regularly

KUBIYA_BASE_URL

KUBIYA_BASE_URL
string
default:"https://api.kubiya.ai/api/v1"
Base URL for Kubiya API endpoints.
Use cases:
  • Custom API endpoint
  • On-premise deployment
  • Development/testing environment

CONTROL_PLANE_URL

CONTROL_PLANE_URL
string
default:"https://control-plane.kubiya.ai"
Control Plane URL for worker registration and management.
Used by:
  • Worker registration
  • Health heartbeats
  • Event streaming
  • Configuration fetching

CONTROL_PLANE_GATEWAY_URL

CONTROL_PLANE_GATEWAY_URL
string
Override Control Plane URL. Takes precedence over CONTROL_PLANE_URL.
Priority: CONTROL_PLANE_GATEWAY_URL > CONTROL_PLANE_URL > default

Worker Configuration

QUEUE_ID

QUEUE_ID
string
required
Worker queue identifier. Must match a queue configured in the Control Plane.
Examples:
  • production-queue
  • staging-queue
  • dev-team-queue
  • high-priority-queue

ENVIRONMENT_NAME

ENVIRONMENT_NAME
string
default:"default"
Environment name for the worker instance.
Use cases:
  • Logical grouping
  • Environment-specific configuration
  • Resource filtering

WORKER_HOSTNAME

WORKER_HOSTNAME
string
default:"auto-detected"
Custom hostname for worker identification.
Default behavior:
  • Auto-detects system hostname
  • In Kubernetes: Uses pod name
  • In Docker: Uses container ID

HEARTBEAT_INTERVAL

HEARTBEAT_INTERVAL
integer
default:"30"
Heartbeat interval in seconds (range: 15-300).
Guidelines:
  • Lower = More frequent health checks
  • Higher = Reduced network overhead
  • Recommended: 15-60 for production

Performance & Concurrency

MAX_CONCURRENT_ACTIVITIES

MAX_CONCURRENT_ACTIVITIES
integer
default:"10"
Maximum number of concurrent activity executions per worker.
Tuning:
  • Low throughput: 5-10
  • Medium throughput: 10-25
  • High throughput: 25-50
  • Consider CPU/memory limits

MAX_CONCURRENT_WORKFLOWS

MAX_CONCURRENT_WORKFLOWS
integer
default:"5"
Maximum number of concurrent workflow executions per worker.
Recommendations:
  • Workflows are heavier than activities
  • Start with 5-10
  • Monitor resource usage
  • Scale horizontally if needed

ACTIVITY_TIMEOUT

ACTIVITY_TIMEOUT
integer
default:"300"
Default activity timeout in seconds.
Guidelines:
  • Short tasks: 60-300s
  • Medium tasks: 300-900s
  • Long tasks: 900-3600s
  • Max: 3600s (1 hour)

WORKFLOW_TIMEOUT

WORKFLOW_TIMEOUT
integer
default:"3600"
Default workflow timeout in seconds.

Logging & Debugging

LOG_LEVEL

LOG_LEVEL
string
default:"INFO"
Logging verbosity level: DEBUG, INFO, WARN, ERROR.
Levels:
  • DEBUG: Detailed debugging information
  • INFO: General informational messages
  • WARN: Warning messages
  • ERROR: Error messages only

KUBIYA_DEBUG

KUBIYA_DEBUG
boolean
default:"false"
Enable comprehensive debug mode.
Enables:
  • Verbose HTTP request/response logging
  • Detailed error stack traces
  • Internal state debugging
  • Performance metrics

KUBIYA_LOG_LEVEL

KUBIYA_LOG_LEVEL
string
default:"INFO"
CLI-specific log level (separate from worker LOG_LEVEL).

Worker Daemon Configuration

MAX_LOG_SIZE

MAX_LOG_SIZE
integer
default:"104857600"
Maximum log file size in bytes before rotation (default: 100MB).

MAX_LOG_BACKUPS

MAX_LOG_BACKUPS
integer
default:"10"
Number of rotated log files to keep.

LOG_COMPRESSION

LOG_COMPRESSION
boolean
default:"true"
Enable gzip compression for rotated logs.

Network & Connectivity

HTTP_PROXY

HTTP_PROXY
string
HTTP proxy server for outbound connections.

HTTPS_PROXY

HTTPS_PROXY
string
HTTPS proxy server for outbound connections.

NO_PROXY

NO_PROXY
string
Comma-separated list of hosts to bypass proxy.

CONNECTION_TIMEOUT

CONNECTION_TIMEOUT
integer
default:"30"
Connection timeout in seconds for HTTP requests.

REQUEST_TIMEOUT

REQUEST_TIMEOUT
integer
default:"300"
Request timeout in seconds for API calls.

Temporal Configuration

TEMPORAL_NAMESPACE

TEMPORAL_NAMESPACE
string
default:"auto-configured"
Temporal namespace (usually auto-configured by Control Plane).
Note: Typically managed by Control Plane. Only set for advanced use cases.

TEMPORAL_HOST

TEMPORAL_HOST
string
default:"auto-configured"
Temporal server host (usually auto-configured by Control Plane).

TEMPORAL_TLS_ENABLED

TEMPORAL_TLS_ENABLED
boolean
default:"true"
Enable TLS for Temporal connections.

Python Environment (Worker)

PYTHON_VERSION

PYTHON_VERSION
string
default:"3.11"
Python version to use for worker virtual environment.
Supported: 3.8, 3.9, 3.10, 3.11, 3.12

PIP_INDEX_URL

PIP_INDEX_URL
string
Custom PyPI index URL for package installation.

PIP_TRUSTED_HOST

PIP_TRUSTED_HOST
string
Trusted host for pip installations (for custom indices).

Resource Limits (Docker/Kubernetes)

MEMORY_LIMIT

MEMORY_LIMIT
string
default:"2Gi"
Memory limit for worker container.

CPU_LIMIT

CPU_LIMIT
string
default:"1000m"
CPU limit for worker container (millicores).

MEMORY_REQUEST

MEMORY_REQUEST
string
default:"512Mi"
Memory request for worker container.

CPU_REQUEST

CPU_REQUEST
string
default:"250m"
CPU request for worker container (millicores).

Feature Flags

ENABLE_METRICS

ENABLE_METRICS
boolean
default:"true"
Enable metrics collection and export.

METRICS_PORT

METRICS_PORT
integer
default:"9090"
Port for Prometheus metrics endpoint.

ENABLE_TRACING

ENABLE_TRACING
boolean
default:"false"
Enable distributed tracing.

TRACING_ENDPOINT

TRACING_ENDPOINT
string
OpenTelemetry tracing endpoint.

Local LiteLLM Proxy Configuration

KUBIYA_ENABLE_LOCAL_PROXY

KUBIYA_ENABLE_LOCAL_PROXY
boolean
default:"false"
Enable local LiteLLM proxy gateway alongside the worker. When enabled, the worker routes all LLM requests through a local proxy instead of the Control Plane gateway.
Use cases:
  • Custom LLM providers (AWS Bedrock, Ollama, etc.)
  • Cost optimization with your own API keys
  • Network isolation and security requirements
  • LLM observability with Langfuse

KUBIYA_PROXY_CONFIG_FILE

KUBIYA_PROXY_CONFIG_FILE
string
Path to LiteLLM proxy configuration file (JSON or YAML). Requires KUBIYA_ENABLE_LOCAL_PROXY=true.
Example config file (litellm_config.yaml):

KUBIYA_PROXY_CONFIG_JSON

KUBIYA_PROXY_CONFIG_JSON
string
Inline LiteLLM proxy configuration as JSON string. Requires KUBIYA_ENABLE_LOCAL_PROXY=true. Alternative to KUBIYA_PROXY_CONFIG_FILE.
Priority: KUBIYA_PROXY_CONFIG_FILE takes precedence over KUBIYA_PROXY_CONFIG_JSON if both are set.

KUBIYA_MODEL

KUBIYA_MODEL
string
Explicit model ID to override agent/team configuration. When set, all LLM requests will use this model regardless of agent settings. Useful for testing, cost control, or debugging.
Use cases:
  • Testing specific models without changing agent configuration
  • Cost control by forcing cheaper models
  • Debugging model-specific issues
  • Local development with specific LLM providers
Priority: CLI flag --model takes precedence over KUBIYA_MODEL environment variable.

CLI-Specific Variables

KUBIYA_DEFAULT_RUNNER

KUBIYA_DEFAULT_RUNNER
string
Default runner for workflow and tool execution.

KUBIYA_DEFAULT_ENVIRONMENT

KUBIYA_DEFAULT_ENVIRONMENT
string
default:"default"
Default environment for resource operations.

KUBIYA_OUTPUT_FORMAT

KUBIYA_OUTPUT_FORMAT
string
default:"table"
Default output format: table, json, yaml.

Environment Profiles

Development Profile

Staging Profile

Production Profile

Configuration Examples

High-Throughput Worker

Long-Running Tasks Worker

Debug Worker

Corporate Proxy Setup

Best Practices

Security

Never commit environment variables with secrets to version control
Use .env files and add them to .gitignore
Rotate API keys regularly (at least quarterly)
Use secrets management tools (Vault, AWS Secrets Manager) in production

Performance

  • Start conservative: Begin with default values
  • Monitor metrics: Track CPU, memory, task execution time
  • Scale horizontally: Add workers before increasing concurrency
  • Test changes: Validate performance improvements

Organization

Validation

Troubleshooting

Common Issues

Check:
  • KUBIYA_API_KEY is set and starts with kby_
  • Key is not expired
  • API endpoint is accessible
Check:
  • CONTROL_PLANE_URL is correct
  • Network connectivity
  • Proxy settings (if applicable)
  • Temporal credentials
Check:
  • MAX_CONCURRENT_ACTIVITIES not too high
  • Resource limits appropriate
  • Activity timeouts reasonable

Next Steps

Worker Management

Deploy and configure workers

Authentication

Set up authentication and control plane access

Troubleshooting

Common issues and solutions

Best Practices

Production deployment guidelines