Global Configuration

Global configuration in Compozy defines system-wide settings that apply across all workflows, agents, and tools. This configuration layer provides the foundation for your entire Compozy installation, handling everything from server settings to database connections, runtime behavior, and system limits.

Sources

Compozy loads configuration from multiple sources in this precedence order:

CLI Flags

Highest precedence - runtime overrides

compozy dev --port 9000 --log-level debug --cors

YAML Configuration

Project-specific settings

compozy.yaml

# Global system configuration
server:
  host: "0.0.0.0"
  port: 5001
  cors_enabled: true
  timeout: 30s

database:
  host: "localhost"
  port: "5432"
  user: "compozy"
  name: "compozy"
  ssl_mode: "require"

Environment Variables

Deployment and secrets

.env

# Server configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=5001
SERVER_CORS_ENABLED=true

# Database configuration
DB_HOST=localhost
DB_PORT=5432
DB_USER=compozy
DB_PASSWORD=secure_password
DB_NAME=compozy
DB_SSL_MODE=require

System Defaults

Lowest precedence - sensible defaults

Built-in defaults ensure Compozy works out-of-the-box for development.

Configuration Validation

Compozy validates all configuration values during startup with helpful error messages:

compozy config validate

Common Validation Errors

Invalid port number: Port must be between 1 and 65535

Invalid environment: Environment must be one of: development, staging, production

Invalid log level: Log level must be one of: debug, info, warn, error

Invalid SSL mode: SSL mode must be one of: disable, require, verify-full

Security Considerations

Follow these best practices to help keep your application and sensitive data secure when configuring Compozy. Proper security measures reduce the risk of accidental exposure or unauthorized access to secrets and configuration files.

Use Environment Variables
Store all secrets in environment variables, never in YAML files
File Permissions
Restrict access to configuration files with proper file permissions
Connection Security
Use SSL/TLS for all database and external service connections
Secrets Management
Use external secrets management for production deployments

Performance Tuning

Fine-tuning your Compozy configuration can help you achieve optimal performance and simplify troubleshooting. The following sections provide guidance on adjusting key parameters and inspecting your configuration.

Resource Optimization

compozy.yaml

runtime:
  async_token_counter_workers: 8          # Increase for high throughput
  async_token_counter_buffer_size: 500    # Larger buffer for bursts

limits:
  max_nesting_depth: 10                   # Reduce for simpler workflows
  max_message_content: 20480              # Increase for complex messages
  parent_update_batch_size: 200           # Larger batches for efficiency

Debugging

Compozy provides a comprehensive set of tools for inspecting and debugging your configuration. The following sections provide guidance on using these tools to troubleshoot issues and optimize your configuration.

# Show all configuration values
compozy config show

# Show as JSON
compozy config show --format json

# Show as YAML
compozy config show --format yaml