Development Commands

Development server commands for Compozy with hot reload and debugging

The compozy dev and compozy start commands provide development and production server capabilities for your Compozy workflows.

Development Server

compozy dev

Start the development server with hot reload and enhanced debugging:

# Start development server with defaults
compozy dev

# Start with custom port
compozy dev --port 3000

# Enable debug logging
compozy dev --debug

# Disable hot reload
compozy dev --no-watch

# Specify custom config
compozy dev --config ./dev-config.yaml

Development Features

Hot Reload

Automatically restarts when files change for faster development cycles

Debug Mode

Enhanced logging and error messages for easier troubleshooting

Development Optimized

Faster startup and verbose error reporting for development efficiency

File Watching

Monitors workflows, tools, and config files for automatic updates

Flags

FlagDescriptionDefault
--portServer port5001
--hostServer hostlocalhost
--debugEnable debug loggingfalse
--no-watchDisable file watchingfalse
--watch-dirAdditional directories to watch-
--configPath to config file-
--envEnvironment file to load-

File Watching

The dev server automatically watches these files:

  • compozy.yaml - Project configuration
  • workflows/**/*.yaml - Workflow definitions
  • tools/**/*.ts - TypeScript tools
  • agents/**/*.yaml - Agent configurations
  • entrypoint.ts - Tool entrypoint

Add custom watch directories:

# Watch additional directories
compozy dev --watch-dir ./custom-tools --watch-dir ./lib

# Watch specific file patterns
compozy dev --watch-pattern "**/*.json" --watch-pattern "**/*.md"

Production Server

compozy start

Start the production server with optimized settings:

# Start production server
compozy start

# Start with custom configuration
compozy start --config /etc/compozy/prod.yaml

# Start with specific worker count
compozy start --workers 8

# Enable JSON logging for log aggregation
compozy start --log-json

# Set log level
compozy start --log-level warn

Production Features

Performance Optimized

Production-ready configurations for high-performance deployment

Security Hardened

Strict validation and security limits for production safety

Production Logging

Structured logs optimized for monitoring and log aggregation

Resource Management

Configurable worker pools for optimal resource utilization

Flags

FlagDescriptionDefault/Options
--portServer port8080
--hostServer host0.0.0.0
--workersNumber of worker processes-
--log-levelLog leveldebug | info | warn | error
--log-jsonOutput logs in JSON formatfalse
--configPath to config file-
--envEnvironment file to load-

Production Configuration

Recommended production settings:

# prod-config.yaml
server:
  host: "0.0.0.0"
  port: 8080
  workers: 8

api:
  rate_limit: 1000
  timeout: 30s

log:
  level: "info"
  format: "json"
  output: "stdout"

security:
  cors:
    enabled: true
    origins: ["https://app.example.com"]

monitoring:
  metrics: true
  health_check: true

Environment Configuration

Both commands support environment configuration:

# .env.development
COMPOZY_API_KEY=amp_dev_key
COMPOZY_LOG_LEVEL=debug
COMPOZY_DATABASE_HOST=localhost
OPENAI_API_KEY=sk-dev-key

# Use development environment
compozy dev --env .env.development

Debugging Features

Debug Output

When running with --debug, you'll see enhanced output:

[DEBUG] 2024-01-15 10:30:45 Server starting...
[DEBUG] 2024-01-15 10:30:45 Loading configuration from: ./compozy.yaml
[DEBUG] 2024-01-15 10:30:45 Initializing runtime: bun
[DEBUG] 2024-01-15 10:30:45 Loading workflows: 3 found
[DEBUG] 2024-01-15 10:30:45 Loading tools: 5 found
[DEBUG] 2024-01-15 10:30:45 Starting file watcher...
[INFO]  2024-01-15 10:30:46 Server started on http://localhost:8080
[DEBUG] 2024-01-15 10:30:46 Watching: workflows/, tools/, agents/, compozy.yaml

Health Checks

Both servers provide health check endpoints:

# Check if server is running
curl http://localhost:8080/health

# Response
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:45Z"
}

Next Steps