Flightcontrol Configuration
Manage Flightcontrol deployment configurations, usually via flightcontrol.json or flightcontrol.cue .
When to Apply
Use this skill when:
-
Creating or updating flightcontrol.json or flightcontrol.cue
-
Adding, editing, or removing services (web, worker, database, etc.)
-
Configuring environments (production, staging, preview)
-
Setting up build, deploy, or CI runner settings
-
Managing environment variables and cross-service references
-
Troubleshooting deployment configuration issues
Canonical Schema and Docs
The hosted JSON schema is the source of truth for all properties, defaults, and validation rules.
Always include the schema in config files for editor validation and autocompletion:
{ "$schema": "https://app.flightcontrol.dev/schema.json", "environments": [] }
Minimal Structure
{ "$schema": "https://app.flightcontrol.dev/schema.json", "envVariables": {}, "environments": [ { "id": "production", "name": "Production", "region": "us-west-2", "source": { "branch": "main" }, "services": [] } ] }
Core Concepts
-
Root: envVariables apply to every environment and service.
-
Environment: id , name , region , source , services , optional envVariables , optional vpc .
-
Service: id , name , type , optional envVariables , optional dependsOn , optional watchPaths .
Service Type Quick Guide
-
web : public HTTP service with load balancing and CDN.
-
web-private : internal HTTP service in the VPC.
-
worker : background processes, no HTTP port.
-
scheduler : cron-based jobs.
-
static : static site hosted on S3 + CloudFront.
-
rds : managed Postgres/MySQL/MariaDB database.
-
elasticache : managed Redis or Valkey cache.
-
lambda-function : Lambda with Docker image or zip build.
-
network-server : TCP/UDP/gRPC via Network Load Balancer.
-
s3 : managed S3 bucket.
Example Snippets
Web Service
{ "id": "api", "name": "API Server", "type": "web", "buildType": "nixpacks", "cpu": 0.5, "memory": 1, "port": 3000, "minInstances": 1, "maxInstances": 3 }
Worker Service
{ "id": "worker", "name": "Background Worker", "type": "worker", "buildType": "nixpacks", "cpu": 0.5, "memory": 1, "startCommand": "npm run worker" }
Scheduler Service
{ "id": "cron", "name": "Scheduled Tasks", "type": "scheduler", "buildType": "nixpacks", "cpu": 0.5, "memory": 1, "jobs": { "daily-report": { "schedule": "0 0 * * *", "startCommand": ["node", "scripts/daily-report.js"] } } }
Static Site
{ "id": "frontend", "name": "Frontend", "type": "static", "buildType": "nixpacks", "buildCommand": "npm run build", "outputDirectory": "dist", "singlePageApp": true }
RDS Database
{ "id": "db", "name": "Database", "type": "rds", "engine": "postgres", "engineVersion": "16", "instanceSize": "db.t4g.micro", "storage": 20, "private": true }
ElastiCache
{ "id": "redis", "name": "Redis Cache", "type": "elasticache", "engine": "redis", "engineVersion": "7.1", "instanceSize": "cache.t4g.micro" }
Lambda Function (Image)
{ "id": "lambda-api", "name": "Lambda API", "type": "lambda-function", "buildType": "docker", "dockerfilePath": "./Dockerfile.lambda", "lambda": { "packageType": "image", "memory": 512, "timeoutSecs": 30 } }
Network Server
{ "id": "grpc-api", "name": "gRPC API", "type": "network-server", "buildType": "docker", "cpu": 1, "memory": 2, "ports": [ { "port": 50051, "protocol": "grpc", "healthCheck": {} } ] }
S3 Bucket
{ "id": "uploads", "name": "User Uploads", "type": "s3", "bucketNameBase": "myapp-uploads" }
Environment Variables
Environment variables can be set at three levels: project, environment, service. Lower levels override higher.
Static Values
"envVariables": { "NODE_ENV": "production", "DEBUG": false }
From Service
"DATABASE_URL": { "fromService": { "id": "db", "value": "dbConnectionString" } }
From Parameter Store or Secrets Manager
"STRIPE_SECRET_KEY": { "fromParameterStore": "myapp/stripe/secret_key" }
"DB_PASSWORD": { "fromSecretsManager": "arn:aws:secretsmanager:us-west-2:123456789:secret:myapp/db-password" }
Preview Environments
{ "id": "preview", "name": "Preview", "region": "us-west-2", "source": { "pr": true, "trigger": "push", "filter": { "toBranches": ["main"], "fromBranches": ["feature/**"] } }, "services": [] }
Build & Deploy Commands
When buildType is nixpacks
- All build, deploy, and start commands are single string
When buildType is Dockerfile
-
The pre and post deploy and start commands will be passed to the docker image as CMD at runtime
-
The CMD value is passed to the ENTRYPOINT value
-
If ENTRYPOINT not defined, the commands need to be an array like ["/bin/sh", "-c", "pnpm start"]
Validation
After every change to a Flightcontrol config file, validate it using:
npx flightcontrol-validate <config-file>
Exit Codes
-
0 = valid config
-
1 = validation errors (fix before proceeding)
-
2 = file not found or parse error
Example Output
Success:
{ "valid": true, "file": "flightcontrol.json" }
Validation errors:
{ "valid": false, "file": "flightcontrol.json", "errors": { "environments": [ { "services": [ { "memory": "Invalid input: expected number, received string" } ] } ] } }
AI Guidance
-
Always validate with npx flightcontrol-validate <file> after each config edit. Fix any errors and re-validate before proceeding. Only show validation output to the user when there are errors.
-
Always keep $schema and prefer the hosted schema for exact fields and defaults.
-
Changing existing id values will create a new entity. The old one will be orphaned and can be deleted from the dashboard.
-
Validate fromService.id references against existing service IDs.
-
Ensure region consistency for VPC, Parameter Store, and Secrets Manager.
References
-
Flightcontrol Documentation
-
Config documentation
-
Configuration Schema
-
AWS Regions
-
Nixpacks Configuration
-
CUE lang documentation