| name | flightcontrol-config |
| description | Flightcontrol configuration management. Use this skill when adding, editing, creating, or modifying flightcontrol.json or flightcontrol.cue configuration files. Covers services, environments, build settings, and deployment configurations. |
| license | MIT |
| metadata | {"author":"flightcontrol","version":"1.0.0"} |
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.
- Schema:
https://app.flightcontrol.dev/schema.json
- Docs:
https://www.flightcontrol.dev/docs
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 config1 = 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
