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
Debug Mode
Development Optimized
File Watching
Flags
Flag | Description | Default |
---|---|---|
--port | Server port | 5001 |
--host | Server host | localhost |
--debug | Enable debug logging | false |
--no-watch | Disable file watching | false |
--watch-dir | Additional directories to watch | - |
--config | Path to config file | - |
--env | Environment file to load | - |
File Watching
The dev server automatically watches these files:
compozy.yaml
- Project configurationworkflows/**/*.yaml
- Workflow definitionstools/**/*.ts
- TypeScript toolsagents/**/*.yaml
- Agent configurationsentrypoint.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
Security Hardened
Production Logging
Resource Management
Flags
Flag | Description | Default/Options |
---|---|---|
--port | Server port | 8080 |
--host | Server host | 0.0.0.0 |
--workers | Number of worker processes | - |
--log-level | Log level | debug | info | warn | error |
--log-json | Output logs in JSON format | false |
--config | Path to config file | - |
--env | Environment 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
Project Commands
Project commands help you create, configure, and manage Compozy projects. The primary command is `init` for initializing new projects.
Authentication Commands
The `compozy auth` command group provides comprehensive authentication and API key management capabilities. These commands support both interactive TUI and automation-friendly JSON output modes.