> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Complete reference of all CLI and worker configuration environment variables

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

## Quick Reference

<CardGroup cols={2}>
  <Card title="Authentication" icon="key">
    Configure API keys and Control Plane access
  </Card>

  <Card title="Worker Configuration" icon="server">
    Worker behavior and resource limits
  </Card>

  <Card title="Logging & Debug" icon="bug">
    Control logging verbosity and debug output
  </Card>

  <Card title="Performance" icon="gauge">
    Tune concurrency and timeouts
  </Card>
</CardGroup>

## Authentication Variables

### KUBIYA\_API\_KEY

<ParamField path="KUBIYA_API_KEY" type="string" required>
  API authentication key for accessing the Kubiya Control Plane.
</ParamField>

```bash theme={null}
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

<ParamField path="KUBIYA_BASE_URL" type="string" default="https://api.kubiya.ai/api/v1">
  Base URL for Kubiya API endpoints.
</ParamField>

```bash theme={null}
export KUBIYA_BASE_URL="https://api.kubiya.ai/api/v1"
```

**Use cases:**

* Custom API endpoint
* On-premise deployment
* Development/testing environment

***

### CONTROL\_PLANE\_URL

<ParamField path="CONTROL_PLANE_URL" type="string" default="https://control-plane.kubiya.ai">
  Control Plane URL for worker registration and management.
</ParamField>

```bash theme={null}
export CONTROL_PLANE_URL="https://control-plane.kubiya.ai"
```

**Used by:**

* Worker registration
* Health heartbeats
* Event streaming
* Configuration fetching

***

### CONTROL\_PLANE\_GATEWAY\_URL

<ParamField path="CONTROL_PLANE_GATEWAY_URL" type="string">
  Override Control Plane URL. Takes precedence over `CONTROL_PLANE_URL`.
</ParamField>

```bash theme={null}
export CONTROL_PLANE_GATEWAY_URL="https://cp.company.internal"
```

**Priority:** `CONTROL_PLANE_GATEWAY_URL` > `CONTROL_PLANE_URL` > default

***

## Worker Configuration

### QUEUE\_ID

<ParamField path="QUEUE_ID" type="string" required>
  Worker queue identifier. Must match a queue configured in the Control Plane.
</ParamField>

```bash theme={null}
export QUEUE_ID="production-queue"
```

**Examples:**

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

***

### ENVIRONMENT\_NAME

<ParamField path="ENVIRONMENT_NAME" type="string" default="default">
  Environment name for the worker instance.
</ParamField>

```bash theme={null}
export ENVIRONMENT_NAME="production"
```

**Use cases:**

* Logical grouping
* Environment-specific configuration
* Resource filtering

***

### WORKER\_HOSTNAME

<ParamField path="WORKER_HOSTNAME" type="string" default="auto-detected">
  Custom hostname for worker identification.
</ParamField>

```bash theme={null}
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

<ParamField path="HEARTBEAT_INTERVAL" type="integer" default="30">
  Heartbeat interval in seconds (range: 15-300).
</ParamField>

```bash theme={null}
export HEARTBEAT_INTERVAL="30"
```

**Guidelines:**

* Lower = More frequent health checks
* Higher = Reduced network overhead
* Recommended: 15-60 for production

***

## Performance & Concurrency

### MAX\_CONCURRENT\_ACTIVITIES

<ParamField path="MAX_CONCURRENT_ACTIVITIES" type="integer" default="10">
  Maximum number of concurrent activity executions per worker.
</ParamField>

```bash theme={null}
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

<ParamField path="MAX_CONCURRENT_WORKFLOWS" type="integer" default="5">
  Maximum number of concurrent workflow executions per worker.
</ParamField>

```bash theme={null}
export MAX_CONCURRENT_WORKFLOWS="10"
```

**Recommendations:**

* Workflows are heavier than activities
* Start with 5-10
* Monitor resource usage
* Scale horizontally if needed

***

### ACTIVITY\_TIMEOUT

<ParamField path="ACTIVITY_TIMEOUT" type="integer" default="300">
  Default activity timeout in seconds.
</ParamField>

```bash theme={null}
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

<ParamField path="WORKFLOW_TIMEOUT" type="integer" default="3600">
  Default workflow timeout in seconds.
</ParamField>

```bash theme={null}
export WORKFLOW_TIMEOUT="7200"  # 2 hours
```

***

## Logging & Debugging

### LOG\_LEVEL

<ParamField path="LOG_LEVEL" type="string" default="INFO">
  Logging verbosity level: DEBUG, INFO, WARN, ERROR.
</ParamField>

```bash theme={null}
export LOG_LEVEL="DEBUG"
```

**Levels:**

* `DEBUG`: Detailed debugging information
* `INFO`: General informational messages
* `WARN`: Warning messages
* `ERROR`: Error messages only

***

### KUBIYA\_DEBUG

<ParamField path="KUBIYA_DEBUG" type="boolean" default="false">
  Enable comprehensive debug mode.
</ParamField>

```bash theme={null}
export KUBIYA_DEBUG=true
```

**Enables:**

* Verbose HTTP request/response logging
* Detailed error stack traces
* Internal state debugging
* Performance metrics

***

### KUBIYA\_LOG\_LEVEL

<ParamField path="KUBIYA_LOG_LEVEL" type="string" default="INFO">
  CLI-specific log level (separate from worker LOG\_LEVEL).
</ParamField>

```bash theme={null}
export KUBIYA_LOG_LEVEL="debug"
```

***

## Worker Daemon Configuration

### MAX\_LOG\_SIZE

<ParamField path="MAX_LOG_SIZE" type="integer" default="104857600">
  Maximum log file size in bytes before rotation (default: 100MB).
</ParamField>

```bash theme={null}
export MAX_LOG_SIZE="209715200"  # 200MB
```

***

### MAX\_LOG\_BACKUPS

<ParamField path="MAX_LOG_BACKUPS" type="integer" default="10">
  Number of rotated log files to keep.
</ParamField>

```bash theme={null}
export MAX_LOG_BACKUPS="20"
```

***

### LOG\_COMPRESSION

<ParamField path="LOG_COMPRESSION" type="boolean" default="true">
  Enable gzip compression for rotated logs.
</ParamField>

```bash theme={null}
export LOG_COMPRESSION="true"
```

***

## Network & Connectivity

### HTTP\_PROXY

<ParamField path="HTTP_PROXY" type="string">
  HTTP proxy server for outbound connections.
</ParamField>

```bash theme={null}
export HTTP_PROXY="http://proxy.company.com:8080"
```

***

### HTTPS\_PROXY

<ParamField path="HTTPS_PROXY" type="string">
  HTTPS proxy server for outbound connections.
</ParamField>

```bash theme={null}
export HTTPS_PROXY="http://proxy.company.com:8443"
```

***

### NO\_PROXY

<ParamField path="NO_PROXY" type="string">
  Comma-separated list of hosts to bypass proxy.
</ParamField>

```bash theme={null}
export NO_PROXY="localhost,127.0.0.1,.company.internal"
```

***

### CONNECTION\_TIMEOUT

<ParamField path="CONNECTION_TIMEOUT" type="integer" default="30">
  Connection timeout in seconds for HTTP requests.
</ParamField>

```bash theme={null}
export CONNECTION_TIMEOUT="60"
```

***

### REQUEST\_TIMEOUT

<ParamField path="REQUEST_TIMEOUT" type="integer" default="300">
  Request timeout in seconds for API calls.
</ParamField>

```bash theme={null}
export REQUEST_TIMEOUT="600"
```

***

## Temporal Configuration

### TEMPORAL\_NAMESPACE

<ParamField path="TEMPORAL_NAMESPACE" type="string" default="auto-configured">
  Temporal namespace (usually auto-configured by Control Plane).
</ParamField>

```bash theme={null}
export TEMPORAL_NAMESPACE="production"
```

**Note:** Typically managed by Control Plane. Only set for advanced use cases.

***

### TEMPORAL\_HOST

<ParamField path="TEMPORAL_HOST" type="string" default="auto-configured">
  Temporal server host (usually auto-configured by Control Plane).
</ParamField>

```bash theme={null}
export TEMPORAL_HOST="temporal.company.internal:7233"
```

***

### TEMPORAL\_TLS\_ENABLED

<ParamField path="TEMPORAL_TLS_ENABLED" type="boolean" default="true">
  Enable TLS for Temporal connections.
</ParamField>

```bash theme={null}
export TEMPORAL_TLS_ENABLED="true"
```

***

## Python Environment (Worker)

### PYTHON\_VERSION

<ParamField path="PYTHON_VERSION" type="string" default="3.11">
  Python version to use for worker virtual environment.
</ParamField>

```bash theme={null}
export PYTHON_VERSION="3.11"
```

**Supported:** 3.8, 3.9, 3.10, 3.11, 3.12

***

### PIP\_INDEX\_URL

<ParamField path="PIP_INDEX_URL" type="string">
  Custom PyPI index URL for package installation.
</ParamField>

```bash theme={null}
export PIP_INDEX_URL="https://pypi.company.internal/simple"
```

***

### PIP\_TRUSTED\_HOST

<ParamField path="PIP_TRUSTED_HOST" type="string">
  Trusted host for pip installations (for custom indices).
</ParamField>

```bash theme={null}
export PIP_TRUSTED_HOST="pypi.company.internal"
```

***

## Resource Limits (Docker/Kubernetes)

### MEMORY\_LIMIT

<ParamField path="MEMORY_LIMIT" type="string" default="2Gi">
  Memory limit for worker container.
</ParamField>

```bash theme={null}
export MEMORY_LIMIT="4Gi"
```

***

### CPU\_LIMIT

<ParamField path="CPU_LIMIT" type="string" default="1000m">
  CPU limit for worker container (millicores).
</ParamField>

```bash theme={null}
export CPU_LIMIT="2000m"  # 2 CPUs
```

***

### MEMORY\_REQUEST

<ParamField path="MEMORY_REQUEST" type="string" default="512Mi">
  Memory request for worker container.
</ParamField>

```bash theme={null}
export MEMORY_REQUEST="1Gi"
```

***

### CPU\_REQUEST

<ParamField path="CPU_REQUEST" type="string" default="250m">
  CPU request for worker container (millicores).
</ParamField>

```bash theme={null}
export CPU_REQUEST="500m"
```

***

## Feature Flags

### ENABLE\_METRICS

<ParamField path="ENABLE_METRICS" type="boolean" default="true">
  Enable metrics collection and export.
</ParamField>

```bash theme={null}
export ENABLE_METRICS="true"
```

***

### METRICS\_PORT

<ParamField path="METRICS_PORT" type="integer" default="9090">
  Port for Prometheus metrics endpoint.
</ParamField>

```bash theme={null}
export METRICS_PORT="9090"
```

***

### ENABLE\_TRACING

<ParamField path="ENABLE_TRACING" type="boolean" default="false">
  Enable distributed tracing.
</ParamField>

```bash theme={null}
export ENABLE_TRACING="true"
```

***

### TRACING\_ENDPOINT

<ParamField path="TRACING_ENDPOINT" type="string">
  OpenTelemetry tracing endpoint.
</ParamField>

```bash theme={null}
export TRACING_ENDPOINT="http://jaeger:14268/api/traces"
```

***

## Local LiteLLM Proxy Configuration

### KUBIYA\_ENABLE\_LOCAL\_PROXY

<ParamField path="KUBIYA_ENABLE_LOCAL_PROXY" type="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.
</ParamField>

```bash theme={null}
export KUBIYA_ENABLE_LOCAL_PROXY=true
```

**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

<ParamField path="KUBIYA_PROXY_CONFIG_FILE" type="string">
  Path to LiteLLM proxy configuration file (JSON or YAML). Requires `KUBIYA_ENABLE_LOCAL_PROXY=true`.
</ParamField>

```bash theme={null}
export KUBIYA_ENABLE_LOCAL_PROXY=true
export KUBIYA_PROXY_CONFIG_FILE=/path/to/litellm_config.yaml
```

**Example config file** (`litellm_config.yaml`):

```yaml theme={null}
model_list:
  - model_name: bedrock-claude-3-5-sonnet
    litellm_params:
      model: bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: os.environ/AWS_REGION_NAME

litellm_settings:
  success_callback: ["langfuse"]

environment_variables:
  LANGFUSE_PUBLIC_KEY: "pk-lf-..."
  LANGFUSE_SECRET_KEY: "sk-lf-..."
  LANGFUSE_HOST: "https://cloud.langfuse.com"
```

***

### KUBIYA\_PROXY\_CONFIG\_JSON

<ParamField path="KUBIYA_PROXY_CONFIG_JSON" type="string">
  Inline LiteLLM proxy configuration as JSON string. Requires `KUBIYA_ENABLE_LOCAL_PROXY=true`. Alternative to `KUBIYA_PROXY_CONFIG_FILE`.
</ParamField>

```bash theme={null}
export KUBIYA_ENABLE_LOCAL_PROXY=true
export KUBIYA_PROXY_CONFIG_JSON='{
  "model_list": [
    {
      "model_name": "gpt-4",
      "litellm_params": {
        "model": "azure/gpt-4",
        "api_base": "https://your-instance.openai.azure.com",
        "api_key": "env:AZURE_API_KEY"
      }
    }
  ]
}'
```

**Priority**: `KUBIYA_PROXY_CONFIG_FILE` takes precedence over `KUBIYA_PROXY_CONFIG_JSON` if both are set.

***

### KUBIYA\_MODEL

<ParamField path="KUBIYA_MODEL" type="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.
</ParamField>

```bash theme={null}
export KUBIYA_MODEL="gpt-4"
# or
export KUBIYA_MODEL="azure/gpt-4-turbo"
# or
export KUBIYA_MODEL="bedrock/anthropic.claude-3-5-sonnet"
```

**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

<ParamField path="KUBIYA_DEFAULT_RUNNER" type="string">
  Default runner for workflow and tool execution.
</ParamField>

```bash theme={null}
export KUBIYA_DEFAULT_RUNNER="production-runner"
```

***

### KUBIYA\_DEFAULT\_ENVIRONMENT

<ParamField path="KUBIYA_DEFAULT_ENVIRONMENT" type="string" default="default">
  Default environment for resource operations.
</ParamField>

```bash theme={null}
export KUBIYA_DEFAULT_ENVIRONMENT="production"
```

***

### KUBIYA\_OUTPUT\_FORMAT

<ParamField path="KUBIYA_OUTPUT_FORMAT" type="string" default="table">
  Default output format: table, json, yaml.
</ParamField>

```bash theme={null}
export KUBIYA_OUTPUT_FORMAT="json"
```

***

## Environment Profiles

### Development Profile

```bash theme={null}
# ~/.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

```bash theme={null}
# ~/.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

```bash theme={null}
# ~/.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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

<Check>
  Never commit environment variables with secrets to version control
</Check>

<Check>
  Use `.env` files and add them to `.gitignore`
</Check>

<Check>
  Rotate API keys regularly (at least quarterly)
</Check>

<Check>
  Use secrets management tools (Vault, AWS Secrets Manager) in production
</Check>

### 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

```bash theme={null}
# Create environment-specific files
~/.kubiya/
├── dev.env
├── staging.env
├── prod.env
└── config.yaml

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

### Validation

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Authentication Failed">
    **Check:**

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

    ```bash theme={null}
    echo $KUBIYA_API_KEY
    curl -H "Authorization: Bearer $KUBIYA_API_KEY" \
      $CONTROL_PLANE_URL/api/v1/health
    ```
  </Accordion>

  <Accordion title="Worker Won't Connect">
    **Check:**

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

    ```bash theme={null}
    ping $(echo $CONTROL_PLANE_URL | cut -d/ -f3)
    curl -v $CONTROL_PLANE_URL/health
    ```
  </Accordion>

  <Accordion title="Performance Issues">
    **Check:**

    * `MAX_CONCURRENT_ACTIVITIES` not too high
    * Resource limits appropriate
    * Activity timeouts reasonable

    ```bash theme={null}
    # Monitor resource usage
    top  # or htop

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Worker Management" icon="server" href="/cli/workers">
    Deploy and configure workers
  </Card>

  <Card title="Authentication" icon="key" href="/cli/authentication">
    Set up authentication and control plane access
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/cli/workers#troubleshooting">
    Common issues and solutions
  </Card>

  <Card title="Best Practices" icon="star" href="/cli/workers#best-practices">
    Production deployment guidelines
  </Card>
</CardGroup>