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

# Advanced project configuration
name: my-compozy-project
version: 1.0.0
description: My AI workflow project
author: Your Name
license: MIT

# Comprehensive dependencies
dependencies:
  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"

# Detailed environment settings
environments:
  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
    monitoring:
      enabled: true
      sampleRate: 0.1

# Advanced workflow settings
workflows:
  defaultTimeout: 30000
  maxRetries: 3
  concurrency: 5
  errorHandling:
    retryStrategy: exponential
    maxBackoff: 60000
  monitoring:
    metrics: true
    tracing: true

# Security and access control
security:
  apiKeys:
    required: true
    rotation:
      enabled: true
      interval: "30d"

  authentication:
    type: "oauth2"
    providers:
      - github
      - google
    mfa:
      required: true
      methods:
        - totp
        - sms

# Resource limits and scaling
resources:
  memory: "1Gi"
  cpu: "0.5"
  storage: "10Gi"

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

string

required

The name of your project

string

required

Project version (semver format)

string

Brief project description

string

Project maintainer

string

Project license

object

Project dependencies by type

Show Properties

array

External tools and utilities

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

array

AI agents and assistants

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

array

Pre-built workflow templates

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

object

Environment-specific configurations

Show Properties

object

Local development settings

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

object

Pre-production testing environment

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

object

Production deployment settings

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

object

Workflow execution settings

Show Properties

number

Default timeout in milliseconds

number

Maximum retry attempts

number

Maximum concurrent workflows

object

Error handling configuration

errorHandling:
  retryStrategy: exponential
  maxBackoff: 60000

object

Security and access control settings

Show Properties

object

API key management settings

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

object

Authentication configuration

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

object

Multi-factor authentication settings

mfa:
  required: true
  methods:
    - totp
    - sms

object

Resource limits and scaling configuration

Show Properties

string

Memory allocation (e.g., “1Gi”)

string

CPU allocation (e.g., “0.5”)

string

Storage requirements

object

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?

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

​Project Structure

​Configuration File Structure

​CLI Commands for Configuration

​Environment Variables

​Configuration Options

​Best Practices

​Need Help?

Project Structure

Configuration File Structure

CLI Commands for Configuration

Environment Variables

Configuration Options

Best Practices

Need Help?