Environment Variables

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.

export KUBIYA_API_KEY="kby_your_api_key_here"

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.

export KUBIYA_BASE_URL="https://api.kubiya.ai/api/v1"

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.

export CONTROL_PLANE_URL="https://control-plane.kubiya.ai"

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.

export CONTROL_PLANE_GATEWAY_URL="https://cp.company.internal"

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.

export QUEUE_ID="production-queue"

Examples:

production-queue
staging-queue
dev-team-queue
high-priority-queue

ENVIRONMENT_NAME

string

default:"default"

Environment name for the worker instance.

export ENVIRONMENT_NAME="production"

Use cases:

Logical grouping
Environment-specific configuration
Resource filtering

WORKER_HOSTNAME

string

default:"auto-detected"

Custom hostname for worker identification.

export WORKER_HOSTNAME="worker-us-east-1a"

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).

export HEARTBEAT_INTERVAL="30"

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.

export MAX_CONCURRENT_ACTIVITIES="20"

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.

export MAX_CONCURRENT_WORKFLOWS="10"

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.

export ACTIVITY_TIMEOUT="600"  # 10 minutes

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.

export WORKFLOW_TIMEOUT="7200"  # 2 hours

Logging & Debugging

LOG_LEVEL

string

default:"INFO"

Logging verbosity level: DEBUG, INFO, WARN, ERROR.

export LOG_LEVEL="DEBUG"

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.

export KUBIYA_DEBUG=true

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).

export KUBIYA_LOG_LEVEL="debug"

Worker Daemon Configuration

MAX_LOG_SIZE

integer

default:"104857600"

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

export MAX_LOG_SIZE="209715200"  # 200MB

MAX_LOG_BACKUPS

integer

default:"10"

Number of rotated log files to keep.

export MAX_LOG_BACKUPS="20"

LOG_COMPRESSION

boolean

default:"true"

Enable gzip compression for rotated logs.

export LOG_COMPRESSION="true"

Network & Connectivity

HTTP_PROXY

string

HTTP proxy server for outbound connections.

export HTTP_PROXY="http://proxy.company.com:8080"

HTTPS_PROXY

string

HTTPS proxy server for outbound connections.

export HTTPS_PROXY="http://proxy.company.com:8443"

NO_PROXY

string

Comma-separated list of hosts to bypass proxy.

export NO_PROXY="localhost,127.0.0.1,.company.internal"

CONNECTION_TIMEOUT

integer

default:"30"

Connection timeout in seconds for HTTP requests.

export CONNECTION_TIMEOUT="60"

REQUEST_TIMEOUT

integer

default:"300"

Request timeout in seconds for API calls.

export REQUEST_TIMEOUT="600"

Temporal Configuration

TEMPORAL_NAMESPACE

string

default:"auto-configured"

Temporal namespace (usually auto-configured by Control Plane).

export TEMPORAL_NAMESPACE="production"

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).

export TEMPORAL_HOST="temporal.company.internal:7233"

TEMPORAL_TLS_ENABLED

boolean

default:"true"

Enable TLS for Temporal connections.

export TEMPORAL_TLS_ENABLED="true"

Python Environment (Worker)

PYTHON_VERSION

string

default:"3.11"

Python version to use for worker virtual environment.

export PYTHON_VERSION="3.11"

Supported: 3.8, 3.9, 3.10, 3.11, 3.12

PIP_INDEX_URL

string

Custom PyPI index URL for package installation.

export PIP_INDEX_URL="https://pypi.company.internal/simple"

PIP_TRUSTED_HOST

string

Trusted host for pip installations (for custom indices).

export PIP_TRUSTED_HOST="pypi.company.internal"

Resource Limits (Docker/Kubernetes)

MEMORY_LIMIT

string

default:"2Gi"

Memory limit for worker container.

export MEMORY_LIMIT="4Gi"

CPU_LIMIT

string

default:"1000m"

CPU limit for worker container (millicores).

export CPU_LIMIT="2000m"  # 2 CPUs

MEMORY_REQUEST

string

default:"512Mi"

Memory request for worker container.

export MEMORY_REQUEST="1Gi"

CPU_REQUEST

string

default:"250m"

CPU request for worker container (millicores).

export CPU_REQUEST="500m"

Feature Flags

ENABLE_METRICS

boolean

default:"true"

Enable metrics collection and export.

export ENABLE_METRICS="true"

METRICS_PORT

integer

default:"9090"

Port for Prometheus metrics endpoint.

export METRICS_PORT="9090"

ENABLE_TRACING

boolean

default:"false"

Enable distributed tracing.

export ENABLE_TRACING="true"

TRACING_ENDPOINT

string

OpenTelemetry tracing endpoint.

export TRACING_ENDPOINT="http://jaeger:14268/api/traces"

CLI-Specific Variables

KUBIYA_DEFAULT_RUNNER

string

Default runner for workflow and tool execution.

export KUBIYA_DEFAULT_RUNNER="production-runner"

KUBIYA_DEFAULT_ENVIRONMENT

string

default:"default"

Default environment for resource operations.

export KUBIYA_DEFAULT_ENVIRONMENT="production"

KUBIYA_OUTPUT_FORMAT

string

default:"table"

Default output format: table, json, yaml.

export KUBIYA_OUTPUT_FORMAT="json"

Environment Profiles

Development Profile

# ~/.kubiya/dev.env
export KUBIYA_API_KEY="kby_dev_key"
export CONTROL_PLANE_URL="https://dev-control-plane.kubiya.ai"
export LOG_LEVEL="DEBUG"
export KUBIYA_DEBUG=true
export HEARTBEAT_INTERVAL="15"
export MAX_CONCURRENT_ACTIVITIES="5"

Staging Profile

# ~/.kubiya/staging.env
export KUBIYA_API_KEY="kby_staging_key"
export CONTROL_PLANE_URL="https://staging-control-plane.kubiya.ai"
export LOG_LEVEL="INFO"
export ENVIRONMENT_NAME="staging"
export HEARTBEAT_INTERVAL="30"
export MAX_CONCURRENT_ACTIVITIES="10"

Production Profile

# ~/.kubiya/prod.env
export KUBIYA_API_KEY="kby_prod_key"
export CONTROL_PLANE_URL="https://control-plane.kubiya.ai"
export LOG_LEVEL="WARN"
export ENVIRONMENT_NAME="production"
export HEARTBEAT_INTERVAL="30"
export MAX_CONCURRENT_ACTIVITIES="25"
export MAX_CONCURRENT_WORKFLOWS="15"
export ACTIVITY_TIMEOUT="900"
export ENABLE_METRICS="true"

Configuration Examples

High-Throughput Worker

export KUBIYA_API_KEY="kby_your_key"
export QUEUE_ID="high-throughput-queue"
export LOG_LEVEL="INFO"
export MAX_CONCURRENT_ACTIVITIES="50"
export MAX_CONCURRENT_WORKFLOWS="25"
export HEARTBEAT_INTERVAL="15"
export ACTIVITY_TIMEOUT="300"

Long-Running Tasks Worker

export KUBIYA_API_KEY="kby_your_key"
export QUEUE_ID="long-tasks-queue"
export LOG_LEVEL="INFO"
export MAX_CONCURRENT_ACTIVITIES="5"
export MAX_CONCURRENT_WORKFLOWS="3"
export ACTIVITY_TIMEOUT="3600"
export WORKFLOW_TIMEOUT="7200"

Debug Worker

export KUBIYA_API_KEY="kby_your_key"
export QUEUE_ID="debug-queue"
export LOG_LEVEL="DEBUG"
export KUBIYA_DEBUG=true
export HEARTBEAT_INTERVAL="15"
export MAX_CONCURRENT_ACTIVITIES="1"
export ENABLE_TRACING="true"

Corporate Proxy Setup

export KUBIYA_API_KEY="kby_your_key"
export CONTROL_PLANE_URL="https://control-plane.kubiya.ai"
export HTTP_PROXY="http://proxy.corp.com:8080"
export HTTPS_PROXY="http://proxy.corp.com:8443"
export NO_PROXY="localhost,127.0.0.1,.corp.internal"
export PIP_INDEX_URL="https://pypi.corp.internal/simple"
export PIP_TRUSTED_HOST="pypi.corp.internal"

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

# Create environment-specific files
~/.kubiya/
├── dev.env
├── staging.env
├── prod.env
└── config.yaml

# Load appropriate environment
source ~/.kubiya/prod.env

Validation

# Verify configuration
echo $KUBIYA_API_KEY | cut -c1-4  # Should show "kby_"
echo $CONTROL_PLANE_URL
echo $LOG_LEVEL

# Test connectivity
curl -I $CONTROL_PLANE_URL/health

# Validate worker setup
kubiya worker start --queue-id=test --type=local --dry-run

Troubleshooting

Common Issues

Authentication Failed

Check:

KUBIYA_API_KEY is set and starts with kby_
Key is not expired
API endpoint is accessible

echo $KUBIYA_API_KEY
curl -H "Authorization: Bearer $KUBIYA_API_KEY" \
  $CONTROL_PLANE_URL/api/v1/health

Worker Won't Connect

Check:

CONTROL_PLANE_URL is correct
Network connectivity
Proxy settings (if applicable)
Temporal credentials

ping $(echo $CONTROL_PLANE_URL | cut -d/ -f3)
curl -v $CONTROL_PLANE_URL/health

Performance Issues

Check:

MAX_CONCURRENT_ACTIVITIES not too high
Resource limits appropriate
Activity timeouts reasonable

# Monitor resource usage
top  # or htop

# Check worker logs
tail -f ~/.kubiya/workers/<queue-id>/logs/worker.log | grep "resource"

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

Getting Started

Core Operations

Advanced

​Quick Reference

Authentication

Worker Configuration

Logging & Debug

Performance

​Authentication Variables

​KUBIYA_API_KEY

​KUBIYA_BASE_URL

​CONTROL_PLANE_URL

​CONTROL_PLANE_GATEWAY_URL

​Worker Configuration

​QUEUE_ID

​ENVIRONMENT_NAME

​WORKER_HOSTNAME

​HEARTBEAT_INTERVAL

​Performance & Concurrency

​MAX_CONCURRENT_ACTIVITIES

​MAX_CONCURRENT_WORKFLOWS

​ACTIVITY_TIMEOUT

​WORKFLOW_TIMEOUT

​Logging & Debugging

​LOG_LEVEL

​KUBIYA_DEBUG

​KUBIYA_LOG_LEVEL

​Worker Daemon Configuration

​MAX_LOG_SIZE

​MAX_LOG_BACKUPS

​LOG_COMPRESSION

​Network & Connectivity

​HTTP_PROXY

​HTTPS_PROXY

​NO_PROXY

​CONNECTION_TIMEOUT

​REQUEST_TIMEOUT

​Temporal Configuration

​TEMPORAL_NAMESPACE

​TEMPORAL_HOST

​TEMPORAL_TLS_ENABLED

​Python Environment (Worker)

​PYTHON_VERSION

​PIP_INDEX_URL

​PIP_TRUSTED_HOST

​Resource Limits (Docker/Kubernetes)

​MEMORY_LIMIT

​CPU_LIMIT

​MEMORY_REQUEST

​CPU_REQUEST

​Feature Flags

​ENABLE_METRICS

​METRICS_PORT

​ENABLE_TRACING

​TRACING_ENDPOINT

​CLI-Specific Variables

​KUBIYA_DEFAULT_RUNNER

​KUBIYA_DEFAULT_ENVIRONMENT

​KUBIYA_OUTPUT_FORMAT

​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

​Performance

​Organization

​Validation

​Troubleshooting

​Common Issues

​Next Steps

Worker Management

Authentication

Troubleshooting

Best Practices

Quick Reference

Authentication Variables

KUBIYA_API_KEY

KUBIYA_BASE_URL

CONTROL_PLANE_URL

CONTROL_PLANE_GATEWAY_URL

Worker Configuration

QUEUE_ID

ENVIRONMENT_NAME

WORKER_HOSTNAME

HEARTBEAT_INTERVAL

Performance & Concurrency

MAX_CONCURRENT_ACTIVITIES

MAX_CONCURRENT_WORKFLOWS

ACTIVITY_TIMEOUT

WORKFLOW_TIMEOUT

Logging & Debugging

LOG_LEVEL

KUBIYA_DEBUG

KUBIYA_LOG_LEVEL

Worker Daemon Configuration

MAX_LOG_SIZE

MAX_LOG_BACKUPS

LOG_COMPRESSION

Network & Connectivity

HTTP_PROXY

HTTPS_PROXY

NO_PROXY

CONNECTION_TIMEOUT

REQUEST_TIMEOUT

Temporal Configuration

TEMPORAL_NAMESPACE

TEMPORAL_HOST

TEMPORAL_TLS_ENABLED

Python Environment (Worker)

PYTHON_VERSION

PIP_INDEX_URL

PIP_TRUSTED_HOST

Resource Limits (Docker/Kubernetes)

MEMORY_LIMIT

CPU_LIMIT

MEMORY_REQUEST

CPU_REQUEST

Feature Flags

ENABLE_METRICS

METRICS_PORT

ENABLE_TRACING

TRACING_ENDPOINT

CLI-Specific Variables

KUBIYA_DEFAULT_RUNNER

KUBIYA_DEFAULT_ENVIRONMENT

KUBIYA_OUTPUT_FORMAT

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

Performance

Organization

Validation

Troubleshooting

Common Issues

Next Steps