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:

{
  "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:

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

Execution Context

Contains fully resolved configuration for runtime execution:

{
  "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:

{
  "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:

{
  "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:

Server level: Most specific configuration
Registry level: Shared configuration across servers
Organization level: Global organizational defaults

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "errorHandling": {
    "missingVariables": "leave-placeholder",
    "invalidTemplates": "log-and-skip",
    "secretAccessDenied": "use-fallback"
  }
}

Configuration Validation Errors

Provide clear error messages:

{
  "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:

{
  "debug": {
    "configurationManagement": {
      "enabled": true,
      "logTemplateResolution": true,
      "logSecretAccess": false,
      "logContextSwitching": true
    }
  }
}

Migration Guide

From Legacy System

When migrating from older configuration systems:

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

Template Syntax Migration

Convert legacy templates to new format:

{
  "legacy": "${{ secrets.API_KEY }}",
  "new": "{secret.API_KEY}"
}

Next Steps

Learn about Template Interpolation for detailed syntax
Explore Variables for non-sensitive configuration
Check Secrets for sensitive data management
Review Server configuration for complete examples

Get Started

Using Pylee

Understanding Pylee

MCP Servers

Support

​Configuration Management

​Overview

​Configuration Contexts

​Display Context

​Copy Context

​Execution Context

​Template Interpolation

​Basic Syntax

​Variable Prefixes

​Precedence Resolution

​Secret Management

​Secure Storage

​Context-Aware Redaction

​Multi-Level Secret Resolution

​Configuration Generation

​Dynamic Configuration Snippets

​Environment-Specific Generation

​Advanced Features

​Nested Configuration Processing

​Configuration Validation

​Configuration Inheritance

​Integration Patterns

​Connect Button Integration

​URL Handler Integration

​Best Practices

​Security Guidelines

​Configuration Organization

​Template Management

​Environment Management

​Error Handling

​Template Resolution Errors

​Configuration Validation Errors

​Performance Considerations

​Caching Strategy

​Memory Management

​Troubleshooting

​Common Issues

​Template Not Resolving

​Context Mismatch

​Precedence Issues

​Debugging Tools

​Migration Guide

​From Legacy System

​Template Syntax Migration

​Next Steps

Configuration Management

Overview

Configuration Contexts

Display Context

Copy Context

Execution Context

Template Interpolation

Basic Syntax

Variable Prefixes

Precedence Resolution

Secret Management

Secure Storage

Context-Aware Redaction

Multi-Level Secret Resolution

Configuration Generation

Dynamic Configuration Snippets

Environment-Specific Generation

Advanced Features

Nested Configuration Processing

Configuration Validation

Configuration Inheritance

Integration Patterns

Connect Button Integration

URL Handler Integration

Best Practices

Security Guidelines

Configuration Organization

Template Management

Environment Management

Error Handling

Template Resolution Errors

Configuration Validation Errors

Performance Considerations

Caching Strategy

Memory Management

Troubleshooting

Common Issues

Template Not Resolving

Context Mismatch

Precedence Issues

Debugging Tools

Migration Guide

From Legacy System

Template Syntax Migration

Next Steps