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

# Dynamic Configuration

> Understand how configuration flows through layers, inheritance rules, and how to use runtime overrides for environment-specific behavior.

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

<Steps>
  <Step title="Layer 1: Variant Defaults">
    **Source**: Built-in variant templates

    Base configuration provided by the variant you select (Read Only, Full Access, etc.)

    ```json theme={null}
    {
      "enable_read_file": true,
      "enable_save_file": true,
      "base_dir": "/",
      "timeout": 60
    }
    ```
  </Step>

  <Step title="Layer 2: Skill Instance">
    **Source**: Your skill creation/configuration

    Custom settings you define when creating the skill instance

    ```json theme={null}
    {
      "base_dir": "/opt/myapp",  // Overrides variant default
      "allowed_extensions": ["yaml", "json"]  // New setting
    }
    ```
  </Step>

  <Step title="Layer 3: Entity-Level">
    **Source**: Team, Agent, or Environment configuration

    Settings that apply to all skills used by that entity

    ```json theme={null}
    {
      "timeout": 120  // Overrides previous layers
    }
    ```
  </Step>

  <Step title="Layer 4: Runtime">
    **Source**: Execution context (environment variables, dynamic parameters)

    Final overrides that apply at execution time

    ```json theme={null}
    {
      "base_dir": "/opt/myapp/production"  // Overrides all layers
    }
    ```
  </Step>
</Steps>

***

## Precedence Rules

### Last Layer Wins

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

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

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

<Tabs>
  <Tab title="Environment Variables">
    ### Using Environment Variables

    Reference environment variables in your skill configuration for dynamic behavior:

    ```json theme={null}
    {
      "configuration": {
        "base_dir": "{{ENVIRONMENT_BASE_DIR}}",  // Variable reference
        "timeout": "{{TIMEOUT_SECONDS:60}}",  // With default fallback
        "allowed_extensions": "{{FILE_TYPES}}"
      }
    }
    ```

    **Setting Environment Variables:**

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

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

    <Tip>
      Use the `{{VAR:default}}` syntax to provide fallback values when environment variables aren't set.
    </Tip>
  </Tab>

  <Tab title="Team-Level">
    ### Team-Level Configuration

    Apply configuration overrides to all agents within a team:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Agent-Specific">
    ### Agent-Specific Overrides

    Fine-tune configuration for individual agents:

    ```json theme={null}
    // 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)
  </Tab>

  <Tab title="Environment Promotion">
    ### Environment Promotion Pattern

    Use different configurations across dev, staging, and production:

    ```json theme={null}
    // 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.
  </Tab>
</Tabs>

***

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

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

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

```json theme={null}
// 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:

```json theme={null}
// 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:

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

<AccordionGroup>
  <Accordion title="Override Not Taking Effect" icon="triangle-exclamation">
    **Problem**: Configuration change isn't being applied

    **Solutions**:

    1. **Check Layer Precedence**: A higher layer may be overriding your setting
       ```bash theme={null}
       kubiya skill get <skill-id> --effective-config
       ```
    2. **Verify Setting is Overridable**: Check if it's locked by variant
    3. **Review Validation Errors**: Check logs for validation failures
    4. **Confirm Scope**: Ensure override is applied to correct entity (team/agent)
  </Accordion>

  <Accordion title="Unexpected Configuration Values" icon="circle-question">
    **Problem**: Effective configuration doesn't match expectations

    **Solutions**:

    1. **View Effective Config**:
       ```bash theme={null}
       kubiya skill get <skill-id> --effective-config --agent <agent-id>
       ```
    2. **Trace Configuration Layers**:
       ```bash theme={null}
       kubiya skill get <skill-id> --show-layers
       ```
    3. **Check Environment Variables**: Verify runtime variables are set
    4. **Review Inheritance Chain**: Variant → Instance → Team → Agent → Runtime
  </Accordion>

  <Accordion title="Validation Errors" icon="ban">
    **Problem**: Configuration override rejected with validation error

    **Solutions**:

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

  <Accordion title="Environment Variable Not Resolving" icon="code">
    **Problem**: Variable syntax `{{VAR}}` not being replaced

    **Solutions**:

    1. **Check Syntax**: Use `{{VARIABLE_NAME}}` or `{{VARIABLE_NAME:default}}`
    2. **Verify Variable is Set**: Check environment where skill executes
    3. **Quote Properly**: Environment variables in YAML may need quotes
    4. **Check Worker Config**: Ensure worker has access to environment variables
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Variables for Environments" icon="code">
    Use `{{ENV_VAR}}` syntax for settings that differ across dev/staging/prod
  </Card>

  <Card title="Set Defaults in Instance" icon="sliders">
    Define sensible defaults at skill instance level, override only when needed
  </Card>

  <Card title="Team-Level for Shared" icon="users">
    Use team-level config for settings shared across team agents
  </Card>

  <Card title="Document Overrides" icon="file-lines">
    Comment your configuration overrides explaining why they're needed
  </Card>
</CardGroup>

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

***

## Related Pages

<CardGroup cols={2}>
  <Card title="Variant Configuration" icon="code-branch" href="/core-concepts/skills/variant-configuration">
    Learn how variants differ in their default configuration
  </Card>

  <Card title="Skill Variants" icon="code-branch" href="/core-concepts/skills/variants">
    Understand variant types and when to use each
  </Card>

  <Card title="Built-in Skills" icon="layer-group" href="/core-concepts/skills/built-in-skills">
    View all available skills and configuration options
  </Card>

  <Card title="Examples" icon="lightbulb" href="/core-concepts/skills/examples">
    See real-world configuration patterns in action
  </Card>
</CardGroup>