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

​
name
string
required
The name of your project
​
version
string
required
Project version (semver format)
​
description
string
Brief project description
​
author
string
Project maintainer
​
license
string
Project license
​
dependencies
object
Project dependencies by type
​
environments
object
Environment-specific configurations
​
workflows
object
Workflow execution settings
​
security
object
Security and access control settings
​
resources
object
Resource limits and scaling configuration

​
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?