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.
- 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.
- 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.
- Worker registration
- Health heartbeats
- Event streaming
- Configuration fetching
CONTROL_PLANE_GATEWAY_URL
string
Override Control Plane URL. Takes precedence over
CONTROL_PLANE_URL.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.
production-queuestaging-queuedev-team-queuehigh-priority-queue
ENVIRONMENT_NAME
string
default:"default"
Environment name for the worker instance.
- Logical grouping
- Environment-specific configuration
- Resource filtering
WORKER_HOSTNAME
string
default:"auto-detected"
Custom hostname for worker identification.
- 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).
- 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.
- 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.
- 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.
- 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.
DEBUG: Detailed debugging informationINFO: General informational messagesWARN: Warning messagesERROR: Error messages only
KUBIYA_DEBUG
boolean
default:"false"
Enable comprehensive debug mode.
- 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).
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.
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.
- 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.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.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.
- Testing specific models without changing agent configuration
- Cost control by forcing cheaper models
- Debugging model-specific issues
- Local development with specific LLM providers
--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 .gitignoreRotate 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
Authentication Failed
Authentication Failed
Check:
KUBIYA_API_KEYis set and starts withkby_- Key is not expired
- API endpoint is accessible
Worker Won't Connect
Worker Won't Connect
Check:
CONTROL_PLANE_URLis correct- Network connectivity
- Proxy settings (if applicable)
- Temporal credentials
Performance Issues
Performance Issues
Check:
MAX_CONCURRENT_ACTIVITIESnot 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