Variant Configuration

Variants are pre-configured templates that provide different security levels and default configurations for each skill type. Understanding how variants differ helps you choose and customize the right configuration for your use case.

Configuration Inheritance Model

Skills follow a hierarchical configuration model:

Skill Type (base capabilities)
  └── Variant (security template + defaults)
      └── Skill Instance (your customizations)
          └── Runtime (environment overrides)

Each layer inherits from the previous and can override specific settings within security boundaries.

Variant Configuration Matrices

File System Skill

Configuration	Read Only 🟢	Full Access 🟡	Sandboxed 🔵
`enable_read_file`	✅ true	✅ true	✅ true
`enable_save_file`	❌ false (locked)	✅ true	✅ true
`enable_list_files`	✅ true	✅ true	✅ true
`enable_search_files`	✅ true	✅ true	✅ true
`base_dir`	”/"	"/"	"/sandbox” (locked)
Can Override?	Limited	Yes	Medium

Locked Settings:

Read Only: Cannot enable write operations (enable_save_file)
Sandboxed: Cannot change base_dir (prevents sandbox escape)

Shell Skill

Configuration	Safe Commands 🟢	Full Access 🔴	Read Only 🟢
`allowed_commands`	Pre-defined safe list	`["*"]` (all)	View-only commands
`blocked_commands`	Destructive ops	`[]` (none)	All except allowed
`timeout`	30s	300s	30s
Can Override?	Yes	Yes	Limited

Locked Settings:

Safe Commands: Cannot add destructive commands to allowed list
Read Only: Cannot enable write operations

Python Skill

Configuration	Restricted Imports 🟢	Full Access 🔴
`allowed_imports`	Safe std library modules	`["*"]` (unrestricted)
`max_memory`	”512MB"	"2GB”
`timeout`	120s	600s
Can Override?	Yes	Yes

Docker Skill

Configuration	Containers Only 🟡	Full Control 🔴
`allowed_operations`	Container lifecycle	All operations
`network_access`	Limited	Full
`volume_management`	❌ false	✅ true
Can Override?	Yes	Yes

Agent Communication Skill

Configuration	Read Only 🟢	Limited 🟡	Full Orchestration 🔴
`allowed_operations`	Status only	Execute + status	All operations
`allowed_agents`	N/A	Whitelist required	`["*"]` (all)
`max_execution_depth`	N/A	2	5
Can Override?	No	Yes	Yes

Customizing Variants

Using CLI with —variant Flag

# Start with variant template, then customize
kubiya skill create \
  --name "Custom Production Files" \
  --type file_system \
  --variant full_access \
  --config-json '{
    "base_dir": "/opt/production",
    "allowed_extensions": ["yaml", "json", "log"],
    "max_file_size": "10MB"
  }' \
  --enabled

Understanding Locked vs. Overridable Settings

🔒 Locked Settings (Cannot Override)

These settings enforce the variant’s security model and cannot be changed:Read Only Variants:

Any write-enabling flags (enable_save_file, enable_delete)
Destructive command permissions

Sandboxed Variants:

base_dir (prevents escaping the sandbox)
Network access restrictions

Attempting to override locked settings will result in validation errors.

✅ Overridable Settings

These settings can be customized within the variant’s boundaries:Performance Settings:

Timeouts, memory limits, CPU limits
Concurrency limits

Scope Settings:

File extensions (within allowed operations)
Directories (within base_dir restrictions)
Specific command lists (within security boundaries)

Behavioral Settings:

Retry counts, delays
Caching options
Logging levels

Configuration Validation

When you create or update a skill instance, Kubiya validates your configuration:

Configuration Override Attempt
  ↓
1. Does it violate variant security model?
   ↓ No
2. Is the value within acceptable range?
   ↓ Yes
3. Is the setting marked as overridable?
   ↓ Yes
4. ✅ Override Applied

Validation Failures:

# ❌ Attempting to enable writes on Read Only variant
kubiya skill create --type file_system --variant read_only \
  --config-json '{"enable_save_file": true}'

Error: Cannot override locked setting 'enable_save_file' for variant 'read_only'

Practical Examples

Production Logs
Dev Sandbox
Restricted Shell
Multi-Agent

Read-Only Log Monitoring

Use Case: Monitor production logs without modification risk

kubiya skill create \
  --name "Production Log Monitor" \
  --type file_system \
  --variant read_only \
  --config-json '{
    "base_dir": "/var/log/production",
    "allowed_extensions": ["log", "txt"],
    "max_file_size": "100MB"
  }' \
  --enabled

What’s Customized:

base_dir: Restricted to production logs directory
allowed_extensions: Only log files
max_file_size: Prevent reading huge files

What’s Locked:

enable_save_file: false (enforced by variant)
enable_delete: false (enforced by variant)

Development Sandbox Environment

Use Case: Isolated development environment with full access

kubiya skill create \
  --name "Developer Sandbox" \
  --type file_system \
  --variant sandboxed \
  --config-json '{
    "enable_save_file": true,
    "enable_delete": true,
    "max_file_size": "50MB"
  }' \
  --enabled

What’s Customized:

enable_save_file: Allow file creation
enable_delete: Allow file deletion
max_file_size: Reasonable limit for dev

What’s Locked:

base_dir: "/sandbox" (enforced by variant)
Cannot access files outside /sandbox

Safe Command Execution

Use Case: System diagnostics with controlled command set

kubiya skill create \
  --name "System Diagnostics" \
  --type shell \
  --variant safe_commands \
  --config-json '{
    "allowed_commands": [
      "ps", "top", "df", "free",
      "netstat", "systemctl status"
    ],
    "timeout": 60,
    "max_output_size": "5MB"
  }' \
  --enabled

What’s Customized:

allowed_commands: Specific diagnostic commands
timeout: Appropriate for diagnostics
max_output_size: Limit output capture

What’s Enforced:

Destructive commands blocked by variant
Privilege escalation prevented

Controlled Agent Orchestration

Use Case: Delegate to specific specialist agents

kubiya skill create \
  --name "Deployment Orchestrator" \
  --type agent_communication \
  --variant limited \
  --config-json '{
    "allowed_agents": [
      "backend-deploy",
      "frontend-deploy",
      "database-migration"
    ],
    "max_execution_depth": 2,
    "timeout": 1800
  }' \
  --enabled

What’s Customized:

allowed_agents: Whitelist deployment agents
max_execution_depth: Prevent deep recursion
timeout: Long enough for deployments

What’s Enforced:

Cannot call agents outside whitelist
Depth limit prevents infinite loops

Best Practices

Start Restrictive

Begin with the most restrictive variant (Read Only, Safe Commands) and only upgrade when necessary

Use Whitelists

Explicitly list allowed commands, agents, or file extensions rather than relying on blocklists

Set Reasonable Limits

Configure timeouts, memory limits, and file sizes appropriate to your use case

Test in Dev First

Validate variant customizations in development before deploying to production

See Also: For information on how configuration flows through multiple layers (variant → instance → team → runtime), see the Dynamic Configuration Guide.

Skill Variants

Learn about variant types and when to use each

Dynamic Configuration

Understand configuration inheritance and layering

Built-in Skills

View all available skills and their variants

Examples

See real-world configuration patterns

Introduction

Quick Start

Web Interface

Core Concepts

Infrastructure

Variant Configuration

Configuration Inheritance Model

Variant Configuration Matrices

File System Skill

Shell Skill

Python Skill

Docker Skill

Agent Communication Skill

Customizing Variants

Using CLI with —variant Flag

Understanding Locked vs. Overridable Settings

Configuration Validation

Practical Examples

Read-Only Log Monitoring

Development Sandbox Environment

Safe Command Execution

Controlled Agent Orchestration

Best Practices

Start Restrictive

Use Whitelists

Set Reasonable Limits

Test in Dev First

Skill Variants

Dynamic Configuration

Built-in Skills

Examples

​Configuration Inheritance Model

​Variant Configuration Matrices

​File System Skill

​Shell Skill

​Python Skill

​Docker Skill

​Agent Communication Skill

​Customizing Variants

​Using CLI with —variant Flag

​Understanding Locked vs. Overridable Settings

​Configuration Validation

​Practical Examples

​Read-Only Log Monitoring

​Development Sandbox Environment

​Safe Command Execution

​Controlled Agent Orchestration

​Best Practices

Start Restrictive

Use Whitelists

Set Reasonable Limits

Test in Dev First

​Related Pages

Skill Variants

Dynamic Configuration

Built-in Skills

Examples

Configuration Inheritance Model

Variant Configuration Matrices

File System Skill

Shell Skill

Python Skill

Docker Skill

Agent Communication Skill

Customizing Variants

Using CLI with —variant Flag

Understanding Locked vs. Overridable Settings

Configuration Validation

Practical Examples

Read-Only Log Monitoring

Development Sandbox Environment

Safe Command Execution

Controlled Agent Orchestration

Best Practices

Related Pages