Dynamic Configuration

Kubiya uses a multi-layer configuration system that allows you to define base configurations and override them at different levels for maximum flexibility while maintaining security.

Configuration Layers

Skills use a 4-layer configuration model where each layer can override settings from the previous layer:

1. Variant Defaults (base template)
   ↓  Inherits & Overrides
2. Skill Instance Config (your customization)
   ↓  Inherits & Overrides
3. Entity-Level Config (team/agent/environment)
   ↓  Inherits & Overrides
4. Runtime Config (execution-time overrides)
   ↓
FINAL EFFECTIVE CONFIGURATION

Layer 1: Variant Defaults

Source: Built-in variant templatesBase configuration provided by the variant you select (Read Only, Full Access, etc.)

{
  "enable_read_file": true,
  "enable_save_file": true,
  "base_dir": "/",
  "timeout": 60
}

Layer 2: Skill Instance

Source: Your skill creation/configurationCustom settings you define when creating the skill instance

{
  "base_dir": "/opt/myapp",  // Overrides variant default
  "allowed_extensions": ["yaml", "json"]  // New setting
}

Layer 3: Entity-Level

Source: Team, Agent, or Environment configurationSettings that apply to all skills used by that entity

{
  "timeout": 120  // Overrides previous layers
}

Layer 4: Runtime

Source: Execution context (environment variables, dynamic parameters)Final overrides that apply at execution time

{
  "base_dir": "/opt/myapp/production"  // Overrides all layers
}

Precedence Rules

Last Layer Wins

When the same setting appears in multiple layers, the highest layer (closest to runtime) takes precedence:

// Layer 1: Variant Default
{ "timeout": 60 }

// Layer 2: Skill Instance
{ "timeout": 90 }  // ← Overrides Layer 1

// Layer 3: Team Config
{ "timeout": 120 }  // ← Overrides Layers 1 & 2

// Layer 4: Runtime
{ "timeout": 150 }  // ← WINS - Overrides all previous layers

// RESULT: timeout = 150

Complete Example

// Layer 1: Variant Defaults (file_system - full_access)
{
  "enable_read_file": true,
  "enable_save_file": true,
  "base_dir": "/",
  "timeout": 60,
  "max_file_size": "10MB"
}

// Layer 2: Skill Instance Configuration
{
  "base_dir": "/opt/myapp",  // Overrides "/"
  "allowed_extensions": ["yaml", "json"],  // New setting
  "timeout": 90  // Overrides 60
}

// Layer 3: Team-Level Configuration
{
  "timeout": 120,  // Overrides 90
  "base_dir": "/team/workspace"  // Overrides "/opt/myapp"
}

// Layer 4: Runtime Configuration
{
  "base_dir": "/opt/myapp/production"  // Overrides "/team/workspace"
}

// === FINAL EFFECTIVE CONFIGURATION ===
{
  "enable_read_file": true,  // From Layer 1 (variant)
  "enable_save_file": true,  // From Layer 1 (variant)
  "base_dir": "/opt/myapp/production",  // From Layer 4 (runtime) ← HIGHEST
  "timeout": 120,  // From Layer 3 (team)
  "max_file_size": "10MB",  // From Layer 1 (variant)
  "allowed_extensions": ["yaml", "json"]  // From Layer 2 (instance)
}

Dynamic Configuration Examples

Environment Variables
Team-Level
Agent-Specific
Environment Promotion

Using Environment Variables

Reference environment variables in your skill configuration for dynamic behavior:

{
  "configuration": {
    "base_dir": "{{ENVIRONMENT_BASE_DIR}}",  // Variable reference
    "timeout": "{{TIMEOUT_SECONDS:60}}",  // With default fallback
    "allowed_extensions": "{{FILE_TYPES}}"
  }
}

Setting Environment Variables:

# On worker or in environment config
export ENVIRONMENT_BASE_DIR=/opt/production
export TIMEOUT_SECONDS=120
export FILE_TYPES=yaml,json,txt

Effective Configuration at Runtime:

{
  "base_dir": "/opt/production",  // Resolved from env var
  "timeout": 120,  // Resolved from env var
  "allowed_extensions": ["yaml", "json", "txt"]  // Parsed from env var
}

Use the {{VAR:default}} syntax to provide fallback values when environment variables aren’t set.

Team-Level Configuration

Apply configuration overrides to all agents within a team:

{
  "name": "Application Files",
  "type": "file_system",
  "variant": "full_access",
  "configuration": {
    "base_dir": "/opt",
    "timeout": 60
  }
}

// Team Configuration Override
{
  "team_id": "platform-team",
  "skill_overrides": {
    "Application_Files": {  // Matches skill name
      "timeout": 300,  // Longer timeout for team
      "base_dir": "/team/workspace",  // Team-specific directory
      "max_file_size": "50MB"  // Higher limit for team
    }
  }
}

Result: All agents in “platform-team” use the team’s overridden configuration.

Agent-Specific Overrides

Fine-tune configuration for individual agents:

// Skill Instance Configuration
{
  "configuration": {
    "allowed_extensions": ["yaml", "json", "txt", "log"],
    "timeout": 60
  }
}

// Team-Level Override
{
  "team_overrides": {
    "allowed_extensions": ["yaml", "json", "txt"],  // Remove logs
    "timeout": 90
  }
}

// Agent-Specific Override (for production deploy agent)
{
  "agent_overrides": {
    "allowed_extensions": ["yaml"],  // MOST restrictive
    "timeout": 120
  }
}

Precedence:

Production agent: ["yaml"] and 120s (agent override wins)
Other team agents: ["yaml", "json", "txt"] and 90s (team override)
Agents outside team: ["yaml", "json", "txt", "log"] and 60s (instance default)

Environment Promotion Pattern

Use different configurations across dev, staging, and production:

// Base Skill Instance
{
  "configuration": {
    "base_dir": "{{APP_BASE_DIR}}",
    "timeout": "{{SKILL_TIMEOUT:60}}",
    "max_concurrent": "{{MAX_CONCURRENT:5}}"
  }
}

// Development Environment
{
  "dev": {
    "APP_BASE_DIR": "/dev",
    "SKILL_TIMEOUT": 600,  // Long timeout for debugging
    "MAX_CONCURRENT": 10  // More parallelism
  }
}

// Staging Environment
{
  "staging": {
    "APP_BASE_DIR": "/staging",
    "SKILL_TIMEOUT": 300,  // Medium timeout
    "MAX_CONCURRENT": 5  // Standard
  }
}

// Production Environment
{
  "production": {
    "APP_BASE_DIR": "/production",
    "SKILL_TIMEOUT": 60,  // Strict timeout
    "MAX_CONCURRENT": 3  // Conservative
  }
}

Same skill instance adapts to each environment automatically.

Configuration Validation

What Can Be Overridden

Not all settings can be overridden at every layer. Security settings are strictly controlled:

Setting Type	Variant	Instance	Team	Agent	Runtime
Timeouts	✅	✅	✅	✅	✅
Memory Limits	✅	✅	✅	✅	✅
Directories	Locked in some variants	✅	✅	✅	✅
Commands (shell)	Variant-specific	✅	✅	✅	❌
File Extensions	✅	✅	✅	✅	✅
Security Flags	❌ Locked	❌	❌	❌	❌
Variant Type	❌ Locked	❌	❌	❌	❌

Security Settings are Locked: Variant security model settings (like enable_save_file on Read Only variants) cannot be overridden at any layer.

Validation Flow

When a configuration override is attempted:

Configuration Override Submitted
  ↓
1. Check: Does it violate variant security model?
   YES → ❌ REJECT
   NO  → Continue
   ↓
2. Check: Is the value within acceptable range?
   NO  → ❌ REJECT (out of bounds)
   YES → Continue
   ↓
3. Check: Is this setting marked as overridable?
   NO  → ❌ REJECT (locked setting)
   YES → Continue
   ↓
4. Check: Does user have permission to set this at this layer?
   NO  → ❌ REJECT (insufficient permissions)
   YES → Continue
   ↓
5. ✅ ACCEPT - Override Applied

Common Patterns

Pattern 1: Progressive Restriction

Start permissive at skill instance level, then restrict at team/agent levels:

// Skill Instance: Broad permissions
{
  "allowed_extensions": ["*"],
  "allowed_operations": ["read", "write", "list", "delete"]
}

// Team Config: More restrictive
{
  "allowed_extensions": ["yaml", "json", "txt", "log"],
  "allowed_operations": ["read", "write", "list"]
}

// Production Agent: Most restrictive
{
  "allowed_extensions": ["yaml"],
  "allowed_operations": ["read", "list"]
}

Benefit: Single skill instance supports multiple use cases with different security requirements.

Pattern 2: Environment-Aware Defaults

Adjust behavior based on environment without changing skill definition:

// Skill configuration uses variables
{
  "timeout": "{{ENV_TIMEOUT:60}}",
  "retry_count": "{{ENV_RETRIES:3}}",
  "log_level": "{{ENV_LOG_LEVEL:info}}"
}

// Development environment variables:
// ENV_TIMEOUT=600
// ENV_RETRIES=1
// ENV_LOG_LEVEL=debug

// Production environment variables:
// ENV_TIMEOUT=30
// ENV_RETRIES=5
// ENV_LOG_LEVEL=error

Pattern 3: Team Workspace Isolation

Give each team their own workspace while using shared skill:

// Shared Skill Instance
{
  "base_dir": "{{TEAM_WORKSPACE}}"
}

// Platform Team: TEAM_WORKSPACE=/workspaces/platform
// Data Team: TEAM_WORKSPACE=/workspaces/data
// Security Team: TEAM_WORKSPACE=/workspaces/security

Troubleshooting

Override Not Taking Effect

Problem: Configuration change isn’t being appliedSolutions:

Check Layer Precedence: A higher layer may be overriding your setting
kubiya skill get <skill-id> --effective-config
Verify Setting is Overridable: Check if it’s locked by variant
Review Validation Errors: Check logs for validation failures
Confirm Scope: Ensure override is applied to correct entity (team/agent)

Unexpected Configuration Values

Problem: Effective configuration doesn’t match expectationsSolutions:

View Effective Config:

kubiya skill get <skill-id> --effective-config --agent <agent-id>

Trace Configuration Layers:

kubiya skill get <skill-id> --show-layers

Check Environment Variables: Verify runtime variables are set
Review Inheritance Chain: Variant → Instance → Team → Agent → Runtime

Validation Errors

Problem: Configuration override rejected with validation errorSolutions:

Security Violation: Check you’re not trying to override locked settings
Out of Range: Ensure values are within acceptable limits (timeouts, memory, etc.)
Type Mismatch: Verify value types match expected format (string, number, boolean, array)
Permission Denied: Confirm you have rights to set this configuration at this layer

Environment Variable Not Resolving

Problem: Variable syntax {{VAR}} not being replacedSolutions:

Check Syntax: Use {{VARIABLE_NAME}} or {{VARIABLE_NAME:default}}
Verify Variable is Set: Check environment where skill executes
Quote Properly: Environment variables in YAML may need quotes
Check Worker Config: Ensure worker has access to environment variables

Best Practices

Use Variables for Environments

Use {{ENV_VAR}} syntax for settings that differ across dev/staging/prod

Set Defaults in Instance

Define sensible defaults at skill instance level, override only when needed

Team-Level for Shared

Use team-level config for settings shared across team agents

Document Overrides

Comment your configuration overrides explaining why they’re needed

Debugging Tip: Use kubiya skill get <skill-id> --effective-config --agent <agent-id> to see the final resolved configuration after all layers are applied.

Variant Configuration

Learn how variants differ in their default configuration

Skill Variants

Understand variant types and when to use each

Built-in Skills

View all available skills and configuration options

Examples

See real-world configuration patterns in action

Introduction

Quick Start

Web Interface

Core Concepts

Infrastructure

Dynamic Configuration

Configuration Layers

Precedence Rules

Last Layer Wins

Complete Example

Dynamic Configuration Examples

Using Environment Variables

Team-Level Configuration

Agent-Specific Overrides

Environment Promotion Pattern

Configuration Validation

What Can Be Overridden

Validation Flow

Common Patterns

Pattern 1: Progressive Restriction

Pattern 2: Environment-Aware Defaults

Pattern 3: Team Workspace Isolation

Troubleshooting

Best Practices

Use Variables for Environments

Set Defaults in Instance

Team-Level for Shared

Document Overrides

Variant Configuration

Skill Variants

Built-in Skills

Examples

​Configuration Layers

​Precedence Rules

​Last Layer Wins

​Complete Example

​Dynamic Configuration Examples

​Using Environment Variables

​Team-Level Configuration

​Agent-Specific Overrides

​Environment Promotion Pattern

​Configuration Validation

​What Can Be Overridden

​Validation Flow

​Common Patterns

​Pattern 1: Progressive Restriction

​Pattern 2: Environment-Aware Defaults

​Pattern 3: Team Workspace Isolation

​Troubleshooting

​Best Practices

Use Variables for Environments

Set Defaults in Instance

Team-Level for Shared

Document Overrides

​Related Pages

Variant Configuration

Skill Variants

Built-in Skills

Examples

Configuration Layers

Precedence Rules

Last Layer Wins

Complete Example

Dynamic Configuration Examples

Using Environment Variables

Team-Level Configuration

Agent-Specific Overrides

Environment Promotion Pattern

Configuration Validation

What Can Be Overridden

Validation Flow

Common Patterns

Pattern 1: Progressive Restriction

Pattern 2: Environment-Aware Defaults

Pattern 3: Team Workspace Isolation

Troubleshooting

Best Practices

Related Pages