Project Configuration

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

tools:
  - "@compozy/openai-tools@^1.0.0"
  - "@compozy/web-tools@^2.1.0"

agents:
  - "@compozy/assistant@^1.0.0"

workflows:
  - "@compozy/chat-workflow@^1.2.0"

development:
  logLevel: debug
  apiEndpoint: "http://localhost:3000"
  features:
    hotReload: true
    debugMode: true

staging:
  logLevel: info
  apiEndpoint: "https://staging-api.compozy.dev"
  features:
    hotReload: false
    debugMode: false

production:
  logLevel: warn
  apiEndpoint: "https://api.compozy.dev"
  features:
    hotReload: false
    debugMode: false

errorHandling:
  retryStrategy: exponential
  maxBackoff: 60000

apiKeys:
  required: true
  rotation:
    enabled: true
    interval: "30d"

authentication:
  type: "oauth2"
  providers:
    - github
    - google

mfa:
  required: true
  methods:
    - totp
    - sms

scaling:
  minReplicas: 1
  maxReplicas: 5
  targetCPUUtilization: 80

​

Best Practices

​

Need Help?

• Run compozy config --help for detailed configuration commands
• Check our configuration troubleshooting guide
• Join our Discord community for configuration support