Project Setup

Compozy uses a unified configuration system through the compozy.yaml file that manages both application runtime behavior and project-specific AI workflows. This single configuration file contains both infrastructure settings and your AI project definition.

Configuration Architecture

Configuration Structure

The compozy.yaml file contains both application-level settings (server, database, infrastructure) and project-level settings (workflows, models, agents). This unified approach simplifies configuration management while maintaining clear separation of concerns within the file structure.

For detailed configuration properties and validation rules, see:

• Application Schema - Server, database, and infrastructure settings
• Project Schema - Workflows, models, agents, and AI project configuration

Project Structure

When you run compozy init, you get this structure:

Configuration Examples

name: simple-weather-app
version: 1.0.0
description: Simple weather advisory system

workflows:
  - source: ./workflow.yaml

models:
  - provider: groq
    model: llama-3.3-70b-versatile
    api_key: "{{ .env.GROQ_API_KEY }}"

runtime:
  type: bun
  entrypoint: "./entrypoint.ts"
  permissions:
    - --allow-read
    - --allow-net

Schema References

The unified configuration system has detailed schema definitions:

Configuration Precedence

Configuration values are resolved in this order (highest to lowest precedence):

1. CLI Flags: compozy dev --port=3000
2. Environment Variables: COMPOZY_SERVER_PORT=3000
3. Configuration Files: YAML configuration files
4. System Defaults: Built-in safe defaults

Related Documentation