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

# Configuration Management

> Advanced configuration management techniques in Pylee including secret handling, template interpolation, and multi-context processing

# Configuration Management

Pylee's configuration management system provides sophisticated tools for handling complex deployment scenarios, secret management, and dynamic configuration generation. This system supports multiple contexts, template interpolation, and secure secret handling across different environments.

## Overview

The configuration management system in Pylee handles:

* **Multi-context processing**: Different configuration contexts for display, copy, and execution
* **Template interpolation**: Dynamic value substitution using flexible template syntax
* **Secret handling**: Secure management of sensitive information with context-aware redaction
* **Environment-specific configuration**: Seamless switching between development, staging, and production
* **Configuration generation**: Automated generation of connection strings, commands, and environment variables

## Configuration Contexts

### Display Context

Used for showing configuration in the UI with secrets masked for security:

```json theme={null}
{
  "environment": {
    "API_KEY": "[redacted]",
    "DATABASE_URL": "postgresql://user:[redacted]@host:5432/db",
    "DEBUG": "true"
  }
}
```

### Copy Context

Provides full configuration values for copying to clipboard or external tools:

```json theme={null}
{
  "environment": {
    "API_KEY": "sk-1234567890abcdef",
    "DATABASE_URL": "postgresql://user:secret123@host:5432/db",
    "DEBUG": "true"
  }
}
```

### Execution Context

Contains fully resolved configuration for runtime execution:

```json theme={null}
{
  "environment": {
    "API_KEY": "sk-1234567890abcdef",
    "DATABASE_URL": "postgresql://user:secret123@host:5432/db",
    "DEBUG": "true",
    "COMPUTED_HASH": "abc123def456"
  }
}
```

## Template Interpolation

### Basic Syntax

Pylee supports flexible template interpolation using curly brace syntax:

```json theme={null}
{
  "remoteUrl": "https://{HOST}:{PORT}/api/v1",
  "environment": {
    "API_ENDPOINT": "{PROTOCOL}://{HOST}/api",
    "DATABASE_URL": "postgresql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:5432/{DB_NAME}"
  }
}
```

### Variable Prefixes

Use prefixes to explicitly reference variables or secrets:

```json theme={null}
{
  "environment": {
    "API_KEY": "{secret.API_KEY}",
    "DEBUG_MODE": "{var.DEBUG_MODE}",
    "MIXED_CONFIG": "{PROTOCOL}://{var.HOST}:{PORT}/api?key={secret.API_KEY}"
  }
}
```

### Precedence Resolution

Variables and secrets are resolved with the following precedence:

1. **Server level**: Most specific configuration
2. **Registry level**: Shared configuration across servers
3. **Organization level**: Global organizational defaults

```json theme={null}
{
  "organization": {
    "variables": { "API_VERSION": "v1" },
    "secrets": { "MASTER_KEY": "org-secret" }
  },
  "registry": {
    "variables": { "API_VERSION": "v2" },
    "secrets": { "SERVICE_KEY": "registry-secret" }
  },
  "server": {
    "variables": { "DEBUG": "true" },
    "secrets": { "API_KEY": "server-secret" }
  }
}
```

Result: `API_VERSION: "v2"` (registry overrides organization)

## Secret Management

### Secure Storage

Secrets are stored securely and only exposed in appropriate contexts:

```json theme={null}
{
  "secrets": {
    "api_key": {
      "value": "sk-1234567890abcdef",
      "description": "External API authentication key",
      "rotationPolicy": "monthly"
    },
    "database_password": {
      "value": "complex-password-123",
      "description": "Database connection password",
      "rotationPolicy": "quarterly"
    }
  }
}
```

### Context-Aware Redaction

Different contexts receive different levels of secret exposure:

```json theme={null}
{
  "displayContext": {
    "API_KEY": "[redacted]",
    "DATABASE_URL": "postgresql://user:[redacted]@host:5432/db"
  },
  "copyContext": {
    "API_KEY": "sk-1234567890abcdef",
    "DATABASE_URL": "postgresql://user:complex-password-123@host:5432/db"
  }
}
```

### Multi-Level Secret Resolution

Secrets can be defined at multiple levels with proper precedence:

```json theme={null}
{
  "organizationSecrets": {
    "GLOBAL_API_KEY": "org-key-123"
  },
  "registrySecrets": {
    "SHARED_SECRET": "registry-secret-456"
  },
  "serverSecrets": {
    "LOCAL_TOKEN": "server-token-789"
  }
}
```

## Configuration Generation

### Dynamic Configuration Snippets

Generate configuration for different tools and environments:

```json theme={null}
{
  "configurationTemplates": {
    "docker": {
      "template": "docker run -e API_KEY={secret.API_KEY} -e DEBUG={var.DEBUG} myapp",
      "contexts": ["copy", "execution"]
    },
    "kubernetes": {
      "template": {
        "apiVersion": "v1",
        "kind": "Secret",
        "metadata": {
          "name": "app-secrets"
        },
        "data": {
          "api-key": "{secret.API_KEY|base64}",
          "db-password": "{secret.DB_PASSWORD|base64}"
        }
      }
    }
  }
}
```

### Environment-Specific Generation

Generate different configurations based on environment:

```json theme={null}
{
  "environments": {
    "development": {
      "variables": {
        "API_URL": "http://localhost:3000",
        "DEBUG": "true"
      }
    },
    "production": {
      "variables": {
        "API_URL": "https://api.production.com",
        "DEBUG": "false"
      }
    }
  }
}
```

## Advanced Features

### Nested Configuration Processing

Handle complex nested configurations:

```json theme={null}
{
  "configuration": {
    "database": {
      "host": "{DB_HOST}",
      "port": "{DB_PORT}",
      "credentials": {
        "username": "{DB_USER}",
        "password": "{secret.DB_PASSWORD}"
      },
      "options": {
        "ssl": "{var.DB_SSL_ENABLED}",
        "timeout": "{var.DB_TIMEOUT}"
      }
    }
  }
}
```

### Configuration Validation

Ensure configuration integrity:

```json theme={null}
{
  "validation": {
    "required": ["API_KEY", "DATABASE_URL"],
    "types": {
      "API_KEY": "string",
      "PORT": "number",
      "DEBUG": "boolean"
    },
    "patterns": {
      "API_KEY": "^sk-[a-zA-Z0-9]{32}$",
      "DATABASE_URL": "^postgresql://.*$"
    }
  }
}
```

### Configuration Inheritance

Support configuration inheritance and overrides:

```json theme={null}
{
  "baseConfiguration": {
    "environment": {
      "NODE_ENV": "{var.ENVIRONMENT}",
      "LOG_LEVEL": "{var.LOG_LEVEL}"
    }
  },
  "serverConfiguration": {
    "extends": "baseConfiguration",
    "environment": {
      "SERVICE_NAME": "{var.SERVICE_NAME}",
      "PORT": "{var.PORT}"
    }
  }
}
```

## Integration Patterns

### Connect Button Integration

The ConnectButton component uses advanced configuration management:

```json theme={null}
{
  "connectButton": {
    "displayConfig": {
      "command": "docker run -e API_KEY=[redacted] myapp",
      "environment": {
        "API_KEY": "[redacted]",
        "DEBUG": "true"
      }
    },
    "copyConfig": {
      "command": "docker run -e API_KEY=sk-1234567890abcdef myapp",
      "environment": {
        "API_KEY": "sk-1234567890abcdef",
        "DEBUG": "true"
      }
    }
  }
}
```

### URL Handler Integration

Generate complete configurations for external tools:

```json theme={null}
{
  "urlHandlers": {
    "cursor": {
      "url": "vscode://file{PROJECT_PATH}",
      "environment": {
        "WORKSPACE_PATH": "{var.PROJECT_PATH}",
        "API_KEY": "{secret.API_KEY}",
        "CONFIG_FILE": "{var.CONFIG_FILE_PATH}"
      }
    },
    "code": {
      "url": "code://file{PROJECT_PATH}",
      "environment": {
        "WORKSPACE_PATH": "{var.PROJECT_PATH}",
        "DEVELOPMENT_MODE": "{var.DEBUG}"
      }
    }
  }
}
```

## Best Practices

### Security Guidelines

* Never log secret values in plain text
* Use context-appropriate secret exposure
* Implement proper access controls
* Regular secret rotation and auditing

### Configuration Organization

* Group related configuration together
* Use descriptive variable and secret names
* Implement consistent naming conventions
* Document configuration dependencies

### Template Management

* Use clear, readable template syntax
* Implement proper error handling for missing variables
* Test template interpolation across all contexts
* Validate generated configurations

### Environment Management

* Maintain separate configurations for each environment
* Use environment-specific variable overrides
* Implement proper configuration validation
* Test configuration generation in all environments

## Error Handling

### Template Resolution Errors

Handle missing variables gracefully:

```json theme={null}
{
  "errorHandling": {
    "missingVariables": "leave-placeholder",
    "invalidTemplates": "log-and-skip",
    "secretAccessDenied": "use-fallback"
  }
}
```

### Configuration Validation Errors

Provide clear error messages:

```json theme={null}
{
  "validationErrors": {
    "required": "Variable '{name}' is required but not provided",
    "type": "Variable '{name}' expected {expected} but got {actual}",
    "pattern": "Variable '{name}' does not match required pattern"
  }
}
```

## Performance Considerations

### Caching Strategy

* Cache resolved configurations per context
* Implement invalidation on variable/secret changes
* Use lazy loading for expensive operations
* Optimize template compilation

### Memory Management

* Limit configuration size
* Clean up unused configurations
* Use weak references where appropriate
* Monitor memory usage patterns

## Troubleshooting

### Common Issues

#### Template Not Resolving

```
Error: Template '{API_KEY}' could not be resolved
```

**Solutions**:

* Check variable/secret exists at appropriate level
* Verify access permissions
* Ensure correct template syntax

#### Context Mismatch

```
Error: Secret exposed in display context
```

**Solutions**:

* Review context configuration
* Check secret handling rules
* Verify UI component implementation

#### Precedence Issues

```
Error: Expected 'production' but got 'development'
```

**Solutions**:

* Review precedence rules
* Check environment configuration
* Verify variable override hierarchy

### Debugging Tools

Enable configuration debugging:

```json theme={null}
{
  "debug": {
    "configurationManagement": {
      "enabled": true,
      "logTemplateResolution": true,
      "logSecretAccess": false,
      "logContextSwitching": true
    }
  }
}
```

## Migration Guide

### From Legacy System

When migrating from older configuration systems:

1. **Audit existing configurations** for security issues
2. **Map legacy variables** to new template syntax
3. **Implement proper secret handling** with context awareness
4. **Test all configuration contexts** thoroughly
5. **Validate generated configurations** in all environments

### Template Syntax Migration

Convert legacy templates to new format:

```json theme={null}
{
  "legacy": "${{ secrets.API_KEY }}",
  "new": "{secret.API_KEY}"
}
```

## Next Steps

* Learn about [Template Interpolation](/understanding-pylee/template-interpolation) for detailed syntax
* Explore [Variables](/understanding-pylee/variables) for non-sensitive configuration
* Check [Secrets](/understanding-pylee/secrets) for sensitive data management
* Review [Server configuration](/understanding-pylee/servers) for complete examples