Every Compozy project is configured through a compozy.yaml file in the project root directory. This file defines your project’s structure, dependencies, settings, and deployment configurations.
Project Structure After you run compozy init, your project will have the following structure:
my-compozy-project/ ├── .compozy ├── src/ │ ├── tools/ │ ├── agents/ │ ├── tasks/ │ └── workflows/ ├── compozy.yaml # Main configuration file ├── .env # Default environment variables └── .env. < environmen t> # Environment specific variables
This structure helps organize your project’s components and configurations in a clean, maintainable way.
Configuration File Structure The compozy.yaml file is automatically created when you initialize a new project with compozy init. Below are examples of basic and advanced configurations:
# Basic project configuration name : my-compozy-project version : 1.0.0 description : My AI workflow project # Core dependencies dependencies : tools : - "@compozy/openai-tools@^1.0.0" agents : - "@compozy/assistant@^1.0.0" # Simple environment settings environments : development : logLevel : debug apiEndpoint : "http://localhost:3000" production : logLevel : info apiEndpoint : "https://api.compozy.dev" # Basic workflow settings workflows : defaultTimeout : 30000 maxRetries : 3
The basic configuration includes essential settings to get started, while the advanced configuration demonstrates the full range of available options. Choose the configuration that best suits your project’s needs.
CLI Commands for Configuration Manage your configuration using these CLI commands:
# View current configuration compozy config show # Set a configuration value compozy config set key value # Get a specific configuration value compozy config get key # Reset configuration to defaults compozy config reset
Environment Variables Compozy automatically loads environment variables from the following .env files in your project directory (in order of precedence):
.env.local - Local overrides (ignored by git).env.development, .env.test, .env.production - Environment-specific variables.env - Default values
You can reference these environment variables in your configuration using the ${ENV_VAR} syntax:
environments : production : apiKey : ${FLYZT_API_KEY} endpoint : ${API_ENDPOINT}
Configuration Options Project version (semver format)
Brief project description
Project dependencies by type External tools and utilities tools : - "@compozy/openai-tools@^1.0.0" - "@compozy/web-tools@^2.1.0"
AI agents and assistants agents : - "@compozy/assistant@^1.0.0"
Pre-built workflow templates workflows : - "@compozy/chat-workflow@^1.2.0"
Environment-specific configurations Local development settings development : logLevel : debug apiEndpoint : "http://localhost:3000" features : hotReload : true debugMode : true
Pre-production testing environment staging : logLevel : info apiEndpoint : "https://staging-api.compozy.dev" features : hotReload : false debugMode : false
Production deployment settings production : logLevel : warn apiEndpoint : "https://api.compozy.dev" features : hotReload : false debugMode : false
Workflow execution settings Default timeout in milliseconds
Maximum concurrent workflows
Error handling configuration errorHandling : retryStrategy : exponential maxBackoff : 60000
Security and access control settings API key management settings apiKeys : required : true rotation : enabled : true interval : "30d"
Authentication configuration authentication : type : "oauth2" providers : - github - google
Multi-factor authentication settings mfa : required : true methods : - totp - sms
Resource limits and scaling configuration Memory allocation (e.g., “1Gi”)
CPU allocation (e.g., “0.5”)
Auto-scaling configuration scaling : minReplicas : 1 maxReplicas : 5 targetCPUUtilization : 80
Best Practices
Version Control Best Practices
Include compozy.yaml in version control
Use environment variables for sensitive data
Create example configuration files for new contributors
Keep configuration versioned with your code
Environment Management
Define all required environments explicitly
Use consistent naming conventions
Document environment-specific requirements
Test configuration changes in staging first
Security Guidelines
Never commit API keys or secrets
Use environment variables for sensitive data
Implement proper access controls
Regularly rotate security credentials
Resource Planning
Set appropriate resource limits
Configure scaling based on usage patterns
Monitor resource utilization
Plan for peak load scenarios
Need Help?