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.

flightcontrol-config