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 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