> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Configuration

> Configure the Compozy CLI and manage global settings

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:

```sh theme={"dark"}
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:

<CodeGroup>
  ```yaml basic theme={"dark"}
  # 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
  ```

  ```yaml advanced theme={"dark"}
  # 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"
  ```
</CodeGroup>

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:

```bash theme={"dark"}
# 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:

```yaml theme={"dark"}
environments:
  production:
    apiKey: ${FLYZT_API_KEY}
    endpoint: ${API_ENDPOINT}
```

## Configuration Options

<ParamField path="name" type="string" required>
  The name of your project
</ParamField>

<ParamField path="version" type="string" required>
  Project version (semver format)
</ParamField>

<ParamField path="description" type="string">
  Brief project description
</ParamField>

<ParamField path="author" type="string">
  Project maintainer
</ParamField>

<ParamField path="license" type="string">
  Project license
</ParamField>

<ParamField path="dependencies" type="object">
  Project dependencies by type

  <Expandable title="Properties">
    <ParamField path="tools" type="array">
      External tools and utilities

      ```yaml theme={"dark"}
      tools:
        - "@compozy/openai-tools@^1.0.0"
        - "@compozy/web-tools@^2.1.0"
      ```
    </ParamField>

    <ParamField path="agents" type="array">
      AI agents and assistants

      ```yaml theme={"dark"}
      agents:
        - "@compozy/assistant@^1.0.0"
      ```
    </ParamField>

    <ParamField path="workflows" type="array">
      Pre-built workflow templates

      ```yaml theme={"dark"}
      workflows:
        - "@compozy/chat-workflow@^1.2.0"
      ```
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="environments" type="object">
  Environment-specific configurations

  <Expandable title="Properties">
    <ParamField path="development" type="object">
      Local development settings

      ```yaml theme={"dark"}
      development:
        logLevel: debug
        apiEndpoint: "http://localhost:3000"
        features:
          hotReload: true
          debugMode: true
      ```
    </ParamField>

    <ParamField path="staging" type="object">
      Pre-production testing environment

      ```yaml theme={"dark"}
      staging:
        logLevel: info
        apiEndpoint: "https://staging-api.compozy.dev"
        features:
          hotReload: false
          debugMode: false
      ```
    </ParamField>

    <ParamField path="production" type="object">
      Production deployment settings

      ```yaml theme={"dark"}
      production:
        logLevel: warn
        apiEndpoint: "https://api.compozy.dev"
        features:
          hotReload: false
          debugMode: false
      ```
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="workflows" type="object">
  Workflow execution settings

  <Expandable title="Properties">
    <ParamField path="defaultTimeout" type="number">
      Default timeout in milliseconds
    </ParamField>

    <ParamField path="maxRetries" type="number">
      Maximum retry attempts
    </ParamField>

    <ParamField path="concurrency" type="number">
      Maximum concurrent workflows
    </ParamField>

    <ParamField path="errorHandling" type="object">
      Error handling configuration

      ```yaml theme={"dark"}
      errorHandling:
        retryStrategy: exponential
        maxBackoff: 60000
      ```
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="security" type="object">
  Security and access control settings

  <Expandable title="Properties">
    <ParamField path="apiKeys" type="object">
      API key management settings

      ```yaml theme={"dark"}
      apiKeys:
        required: true
        rotation:
          enabled: true
          interval: "30d"
      ```
    </ParamField>

    <ParamField path="authentication" type="object">
      Authentication configuration

      ```yaml theme={"dark"}
      authentication:
        type: "oauth2"
        providers:
          - github
          - google
      ```
    </ParamField>

    <ParamField path="mfa" type="object">
      Multi-factor authentication settings

      ```yaml theme={"dark"}
      mfa:
        required: true
        methods:
          - totp
          - sms
      ```
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="resources" type="object">
  Resource limits and scaling configuration

  <Expandable title="Properties">
    <ParamField path="memory" type="string">
      Memory allocation (e.g., "1Gi")
    </ParamField>

    <ParamField path="cpu" type="string">
      CPU allocation (e.g., "0.5")
    </ParamField>

    <ParamField path="storage" type="string">
      Storage requirements
    </ParamField>

    <ParamField path="scaling" type="object">
      Auto-scaling configuration

      ```yaml theme={"dark"}
      scaling:
        minReplicas: 1
        maxReplicas: 5
        targetCPUUtilization: 80
      ```
    </ParamField>
  </Expandable>
</ParamField>

## Best Practices

<Steps>
  <Step title="Version Control Best Practices" icon="code-branch">
    * 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
  </Step>

  <Step title="Environment Management" icon="server">
    * Define all required environments explicitly
    * Use consistent naming conventions
    * Document environment-specific requirements
    * Test configuration changes in staging first
  </Step>

  <Step title="Security Guidelines" icon="shield">
    * Never commit API keys or secrets
    * Use environment variables for sensitive data
    * Implement proper access controls
    * Regularly rotate security credentials
  </Step>

  <Step title="Resource Planning" icon="chart-line">
    * Set appropriate resource limits
    * Configure scaling based on usage patterns
    * Monitor resource utilization
    * Plan for peak load scenarios
  </Step>
</Steps>

## Need Help?

* Run `compozy config --help` for detailed configuration commands
* Check our [configuration troubleshooting guide](/cli/troubleshooting)
* Join our [Discord community](https://discord.gg/compozy) for configuration support