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

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

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

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

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

Worker Configuration

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

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

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

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

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

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

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

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

Logging & Debugging

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

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

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

Worker Daemon Configuration

MAX_LOG_SIZE

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

MAX_LOG_BACKUPS

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

LOG_COMPRESSION

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

Network & Connectivity

HTTP_PROXY

string
HTTP proxy server for outbound connections.

HTTPS_PROXY

string
HTTPS proxy server for outbound connections.

NO_PROXY

string
Comma-separated list of hosts to bypass proxy.

CONNECTION_TIMEOUT

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

REQUEST_TIMEOUT

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

Temporal Configuration

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

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

TEMPORAL_TLS_ENABLED

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

Python Environment (Worker)

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

string
Custom PyPI index URL for package installation.

PIP_TRUSTED_HOST

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

Resource Limits (Docker/Kubernetes)

MEMORY_LIMIT

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

CPU_LIMIT

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

MEMORY_REQUEST

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

CPU_REQUEST

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

Feature Flags

ENABLE_METRICS

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

METRICS_PORT

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

ENABLE_TRACING

boolean
default:"false"
Enable distributed tracing.

TRACING_ENDPOINT

string
OpenTelemetry tracing endpoint.

Local LiteLLM Proxy Configuration

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

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

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

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

string
Default runner for workflow and tool execution.

KUBIYA_DEFAULT_ENVIRONMENT

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

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