PMDevSolutions · PAMulligan · Jun 13, 2026 · Jun 12, 2026
diff --git a/.claude/CUSTOM-AGENTS-GUIDE.md b/.claude/CUSTOM-AGENTS-GUIDE.md
@@ -89,7 +89,7 @@ Integration testing, contract testing, load testing for APIs.
 
 ### devops-automator (blue)
 Docker, CI/CD pipeline generation, deployment automation.
-- **When to use:** Setting up Docker, creating CI/CD, deploying to Cloudflare Workers, Node.js, AWS Lambda, or Railway
+- **When to use:** Setting up Docker, creating CI/CD, deploying to Cloudflare Workers, Node.js, AWS Lambda, Railway, or Fly.io
 - **Key capabilities:** Multi-stage Docker, GitHub Actions, wrangler deploy, PM2, health endpoints
 
 ---

diff --git a/.claude/agents/devops-automator.md b/.claude/agents/devops-automator.md
@@ -1,6 +1,6 @@
 ---
 name: devops-automator
-description: API deployment and CI/CD specialist for Docker, GitHub Actions, Cloudflare Workers, Node.js, AWS Lambda, and Railway deployments. Use when setting up deployment pipelines, configuring Docker, managing Workers deployments, deploying with SAM, configuring Railway services, or automating build processes.
+description: API deployment and CI/CD specialist for Docker, GitHub Actions, Cloudflare Workers, Node.js, AWS Lambda, Railway, and Fly.io deployments. Use when setting up deployment pipelines, configuring Docker, managing Workers deployments, deploying with SAM, configuring Railway services, deploying to Fly.io Machines, or automating build processes.
 color: blue
 tools: Bash, Read, Write, Grep, MultiEdit
 ---

diff --git a/.claude/pipeline.config.json b/.claude/pipeline.config.json
@@ -68,7 +68,7 @@
     "noAnyTypes": true
   },
   "deployment": {
-    "targets": ["cloudflare-workers", "node-docker", "aws-lambda", "railway"],
+    "targets": ["cloudflare-workers", "node-docker", "aws-lambda", "railway", "fly"],
     "defaultTarget": "cloudflare-workers",
     "cloudflareWorkers": {
       "compatibilityDate": "2024-12-01",
@@ -105,6 +105,17 @@
       "managedPostgres": true,
       "autoDeployFromGitHub": true
     },
+    "fly": {
+      "builder": "dockerfile",
+      "internalPort": 3000,
+      "healthcheckPath": "/health",
+      "autoStopMachines": "stop",
+      "autoStartMachines": true,
+      "minMachinesRunning": 1,
+      "maxMachines": 3,
+      "managedPostgres": true,
+      "autoDeployFromGitHub": false
+    },
     "cicd": {
       "provider": "github-actions",
       "runTests": true,

diff --git a/.claude/skills/deployment-config-generator/SKILL.md b/.claude/skills/deployment-config-generator/SKILL.md
@@ -6,12 +6,14 @@ description: >
   For Node.js, generates Dockerfile and docker-compose.yml with PostgreSQL. For
   AWS Lambda, generates a SAM template (API Gateway HTTP API), esbuild bundling
   config, and an OIDC deploy workflow. For Railway, generates railway.toml
-  (Dockerfile build, health check, start command) and nixpacks.toml. Always
-  generates GitHub Actions CI/CD workflow and .env.example. Keywords: deploy,
-  deployment, wrangler, cloudflare, workers, docker, dockerfile, docker-compose,
-  aws, lambda, sam, api-gateway, serverless, esbuild, oidc, cold-start, railway,
-  nixpacks, paas, github-actions, ci-cd, pipeline, env, configuration,
-  infrastructure
+  (Dockerfile build, health check, start command) and nixpacks.toml. For
+  Fly.io, generates fly.toml (HTTP service, health check, Machine autoscaling,
+  Managed Postgres attachment). Always generates GitHub Actions CI/CD workflow
+  and .env.example. Keywords: deploy, deployment, wrangler, cloudflare,
+  workers, docker, dockerfile, docker-compose, aws, lambda, sam, api-gateway,
+  serverless, esbuild, oidc, cold-start, railway, nixpacks, paas, fly, flyio,
+  flyctl, machines, fly-toml, github-actions, ci-cd, pipeline, env,
+  configuration, infrastructure
 ---
 
 # Deployment Config Generator (Phase 5)
@@ -47,7 +49,7 @@ const spec = JSON.parse(
   await readFile('.claude/plans/build-spec.json', 'utf-8'),
 );
 
-const target = spec.deployment.target; // 'cloudflare-workers' | 'node' | 'aws-lambda' | 'railway'
+const target = spec.deployment.target; // 'cloudflare-workers' | 'node' | 'aws-lambda' | 'railway' | 'fly'
 const authStrategy = spec.auth.strategy;
 ```
 
@@ -410,6 +412,74 @@ cmds = ["pnpm build"]
 cmd = "node dist/index.js"
 ```
 
+### Step 2e -- Fly.io Configuration
+
+If target is `fly`, reuse the Node.js Dockerfile from Step 2b and generate
+`fly.toml`. The canonical template lives in `templates/fly/fly.toml`. Fly.io
+builds Machines from the Dockerfile, so the deployed image is identical to
+the local `docker compose up` image.
+
+```toml
+# api/fly.toml
+app = "my-api"             # globally unique; fly launch sets it
+primary_region = "iad"
+
+[build]
+dockerfile = "Dockerfile"
+
+[env]
+NODE_ENV = "production"
+PORT = "3000"
+LOG_LEVEL = "info"
+
+[http_service]
+internal_port = 3000
+force_https = true
+auto_stop_machines = "stop"
+auto_start_machines = true
+min_machines_running = 1
+
+[http_service.concurrency]
+type = "requests"
+soft_limit = 200
+hard_limit = 250
+
+[[http_service.checks]]
+method = "GET"
+path = "/health"
+interval = "15s"
+timeout = "5s"
+grace_period = "10s"
+
+[[vm]]
+size = "shared-cpu-1x"
+memory = "512mb"
+```
+
+Autoscaling is autostop/autostart: Fly stops idle Machines down to
+`min_machines_running` and restarts them when traffic crosses the concurrency
+`soft_limit`. The ceiling is the number of Machines that exist -- instruct the
+user to run `fly scale count 3` for min 1 / max 3.
+
+Secrets are set with flyctl, not committed (`[env]` holds non-secrets only).
+Attaching Managed Postgres sets `DATABASE_URL` automatically:
+
+```bash
+fly mpg create                          # managed PostgreSQL cluster
+fly mpg attach <cluster-id> -a <app>    # sets DATABASE_URL secret
+fly secrets set JWT_SECRET=$(openssl rand -hex 32)
+```
+
+No deploy workflow is generated by default: `fly deploy` from `api/` builds
+and deploys, gated by the `/health` check. Fly.io does not auto-deploy from
+GitHub -- if the user wants continuous deployment, point them at the
+[GitHub Actions guide](https://fly.io/docs/launch/continuous-deployment-with-github-actions/)
+(`flyctl deploy --remote-only` with a `FLY_API_TOKEN` secret).
+
+Migrations run from the developer's machine through `fly mpg proxy` (the
+production image prunes dev dependencies, so a `release_command` migration
+would need drizzle-kit added to the image first -- see the fly.toml comments).
+
 ### Step 3 -- Generate GitHub Actions CI/CD
 
 ```yaml
@@ -514,6 +584,11 @@ jobs:
       # - run: cd api && pnpm run build:lambda && sam deploy --no-confirm-changeset
       # For Railway: no deploy step -- Railway auto-deploys the connected
       # GitHub repo on push, gated by the /health check (see Step 2d).
+      # For Fly.io (requires a FLY_API_TOKEN secret, see Step 2e):
+      # - uses: superfly/flyctl-actions/setup-flyctl@master
+      # - run: cd api && flyctl deploy --remote-only
+      #   env:
+      #     FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
 
   deploy-production:
     runs-on: ubuntu-latest
@@ -592,6 +667,7 @@ Ensure the API package.json has all necessary scripts:
 | esbuild config | `api/esbuild.config.mjs` | Single-file Lambda bundle build |
 | Railway config | `api/railway.toml` | Build, health check, start command, restart policy |
 | Nixpacks config | `api/nixpacks.toml` | Toolchain pins for the non-Docker Railway build |
+| Fly.io config | `api/fly.toml` | HTTP service, health check, Machine autoscaling |
 | CI/CD workflow | `.github/workflows/ci.yml` | GitHub Actions pipeline |
 | Deploy workflow | `.github/workflows/deploy.yml` | OIDC-based AWS Lambda deploy (Lambda target) |
 | Env template | `.env.example` | Environment variable template |

diff --git a/.claude/skills/schema-intake/SKILL.md b/.claude/skills/schema-intake/SKILL.md
@@ -84,7 +84,7 @@ continuing. Adapt follow-up questions based on responses.
 
 **Question 6 -- Deployment Target**
 > Where will this API be deployed?
-> Options: Cloudflare Workers (default), Node.js / Docker, AWS Lambda, Railway
+> Options: Cloudflare Workers (default), Node.js / Docker, AWS Lambda, Railway, Fly.io
 
 **Question 7 -- Additional Requirements** (optional)
 > Any special requirements? (pagination style, rate limiting, soft deletes, etc.)
@@ -294,7 +294,7 @@ interface BuildSpec {
     sourceType: 'file' | 'interview';
   };
   deployment: {
-    target: 'cloudflare-workers' | 'node' | 'aws-lambda' | 'railway';
+    target: 'cloudflare-workers' | 'node' | 'aws-lambda' | 'railway' | 'fly';
     runtime: string;
   };
   auth: {
@@ -553,7 +553,7 @@ function validateBuildSpec(spec: BuildSpec): string[] {
 | `tdd-from-schema` (Phase 2) | Reads `endpoints` and `auth` to generate test cases |
 | `route-generation` (Phase 3) | Reads `endpoints` to scaffold Hono route handlers |
 | `api-authentication` | Reads `auth` to configure JWT/API key middleware |
-| `deployment-config-generator` | Reads `deployment` to generate wrangler.toml, Dockerfile, SAM template, or railway.toml |
+| `deployment-config-generator` | Reads `deployment` to generate wrangler.toml, Dockerfile, SAM template, railway.toml, or fly.toml |
 | `api-documentation` | Reads the generated OpenAPI spec or regenerates from build-spec |
 
 ### Triggering the Next Phase

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -166,7 +166,7 @@ jobs:
             fi
           done
 
-          for dir in templates/shared templates/cloudflare-workers templates/node-server templates/docker templates/aws-lambda templates/railway; do
+          for dir in templates/shared templates/cloudflare-workers templates/node-server templates/docker templates/aws-lambda templates/railway templates/fly; do
             if [ -d "$dir" ]; then
               echo "  $dir: OK"
             else

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,15 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a **Claude Code-integrated API & backend development framework** providing specialized agents, skills, scripts, and schema-to-API conversion pipelines. Built with TypeScript, Hono (HTTP framework), Drizzle ORM, and PostgreSQL. Deployed to Cloudflare Workers, Node.js, AWS Lambda, or Railway.
+This is a **Claude Code-integrated API & backend development framework** providing specialized agents, skills, scripts, and schema-to-API conversion pipelines. Built with TypeScript, Hono (HTTP framework), Drizzle ORM, and PostgreSQL. Deployed to Cloudflare Workers, Node.js, AWS Lambda, Railway, or Fly.io.
 
 Nerva is the backend counterpart to **Aurelius** (frontend framework).
 
 The framework is designed for:
 - Schema-first API development (OpenAPI spec to working API)
 - OpenAPI-to-working-API conversion with TDD-mandatory development
 - Comprehensive testing (integration tests, contract tests, load tests with k6)
-- Deployment to Cloudflare Workers, Node.js (Docker), AWS Lambda (SAM), or Railway
+- Deployment to Cloudflare Workers, Node.js (Docker), AWS Lambda (SAM), Railway, or Fly.io
 - Full product lifecycle support (engineering, database, testing, DevOps, operations)
 
 ## Project Structure
@@ -40,6 +40,7 @@ project-root/
 │   ├── node-server/        # Node.js server config
 │   ├── aws-lambda/         # SAM template, esbuild config, OIDC deploy workflow
 │   ├── railway/            # Railway config-as-code (railway.toml, nixpacks.toml)
+│   ├── fly/                # Fly.io config (fly.toml)
 │   └── docker/             # Dockerfile, docker-compose
 ├── docs/
 │   ├── schema-to-api/      # Pipeline guide
@@ -59,7 +60,7 @@ project-root/
 
 ```bash
 # Setup a new API project
-./scripts/setup-project.sh my-api --cloudflare  # or --node / --lambda / --railway
+./scripts/setup-project.sh my-api --cloudflare  # or --node / --lambda / --railway / --fly
 
 # Run tests with coverage
 ./scripts/run-tests.sh
@@ -234,7 +235,7 @@ Autonomous 10-phase pipeline that converts an OpenAPI specification into a worki
 - **Schema-first** — OpenAPI spec drives database schema, types, handlers, and tests
 - **Contract testing** — generated tests validate API responses against OpenAPI spec
 - **Load testing** — k6 scripts generated for performance-critical endpoints
-- **Multi-target deployment** — Cloudflare Workers, Node.js, Docker, AWS Lambda, Railway with single config change
+- **Multi-target deployment** — Cloudflare Workers, Node.js, Docker, AWS Lambda, Railway, Fly.io with single config change
 - **Type safety end-to-end** — Drizzle schema to Zod validators to TypeScript types
 - Quality gate: 80%+ coverage, TypeScript strict, security audit, bundle analysis
 - Resumable: TodoWrite tracks progress across interrupted sessions
@@ -491,9 +492,10 @@ pnpm drizzle-kit studio             # Open database GUI
 ./scripts/setup-project.sh my-api --node         # New Node.js project
 ./scripts/setup-project.sh my-api --lambda       # New AWS Lambda (SAM) project
 ./scripts/setup-project.sh my-api --railway      # New Railway project
+./scripts/setup-project.sh my-api --fly          # New Fly.io project
 ```
 
 ---
 
-**Last Updated:** 2026-06-11
+**Last Updated:** 2026-06-12
 **Architecture:** 24 agents, 12 skills, 4 plugins + gh CLI, 9 scripts
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ A Claude Code-integrated API & backend development framework with TypeScript, Ho
 - **12 Development Skills** — Automated workflows for schema parsing, TDD, route generation, authentication, validation, documentation
 - **10-Phase Schema-to-API Pipeline** — Convert OpenAPI specs into fully working, tested API servers with a single command
 - **TDD-Mandatory Development** — Integration tests written before route handlers, hard gate enforced
-- **Four Deployment Targets** — Cloudflare Workers (edge), Node.js (Docker), AWS Lambda (SAM), or Railway (PaaS) with one config change
+- **Five Deployment Targets** — Cloudflare Workers (edge), Node.js (Docker), AWS Lambda (SAM), Railway (PaaS), or Fly.io (global containers) with one config change
 - **Testing Stack** — Vitest, supertest, contract tests against OpenAPI, k6 load tests
 - **Schema-First Design** — Database schemas, types, and validators all derived from your API spec
 
@@ -37,7 +37,7 @@ cd Nerva
 pnpm install
 
 # Initialize a new API project
-./scripts/setup-project.sh my-api --cloudflare   # or --node / --lambda / --railway
+./scripts/setup-project.sh my-api --cloudflare   # or --node / --lambda / --railway / --fly
 
 # Start development
 cd api && pnpm dev
@@ -177,6 +177,7 @@ Full catalog: [`.claude/CUSTOM-AGENTS-GUIDE.md`](.claude/CUSTOM-AGENTS-GUIDE.md)
 | `templates/node-server/` | Dockerfile + docker-compose with PostgreSQL |
 | `templates/aws-lambda/` | SAM template, esbuild config, OIDC deploy workflow |
 | `templates/railway/` | Railway config-as-code + Nixpacks build config |
+| `templates/fly/` | Fly.io config (HTTP service, health check, autoscaling) |
 | `templates/docker/` | Extended Docker with Redis + pgAdmin |
 
 ## Part of the PMDS Framework Series

diff --git a/docs/onboarding/architecture.md b/docs/onboarding/architecture.md
@@ -61,7 +61,7 @@ Shell scripts for common development tasks:
 
 | Script | Purpose |
 |--------|---------|
-| `setup-project.sh` | Initialize a new API project (--cloudflare, --node, --lambda, or --railway) |
+| `setup-project.sh` | Initialize a new API project (--cloudflare, --node, --lambda, --railway, or --fly) |
 | `run-tests.sh` | Vitest test suite with coverage |
 | `check-types.sh` | TypeScript strict mode checking |
 | `security-scan.sh` | Dependency and code security audit |
@@ -71,7 +71,7 @@ Shell scripts for common development tasks:
 | `generate-openapi-docs.sh` | Build API documentation |
 | `generate-client.sh` | Generate typed API client for frontends |
 
-### Templates (6 directories)
+### Templates (7 directories)
 
 Starter configurations for different deployment targets:
 
@@ -82,6 +82,7 @@ Starter configurations for different deployment targets:
 | `templates/node-server/` | Dockerfile + docker-compose with PostgreSQL |
 | `templates/aws-lambda/` | SAM template (API Gateway HTTP API), esbuild config, OIDC deploy workflow |
 | `templates/railway/` | Railway config-as-code (Docker build, health check) + Nixpacks config |
+| `templates/fly/` | Fly.io config (HTTP service, health check, Machine autoscaling) |
 | `templates/docker/` | Extended Docker setup with Redis + pgAdmin |
 
 ## Pipelines

diff --git a/docs/onboarding/quickstart.md b/docs/onboarding/quickstart.md
@@ -32,7 +32,7 @@ If you have an OpenAPI specification file:
 
 ```bash
 # Initialize the project structure
-./scripts/setup-project.sh my-api --cloudflare   # or --node / --lambda / --railway
+./scripts/setup-project.sh my-api --cloudflare   # or --node / --lambda / --railway / --fly
 
 # Open Claude Code and run the pipeline
 /build-from-schema path/to/openapi-spec.yaml

diff --git a/docs/schema-to-api/README.md b/docs/schema-to-api/README.md
@@ -15,7 +15,7 @@ Convert an OpenAPI specification into a fully working, tested API server through
 | 7 | Validation Layer | Generate Zod schemas for request/response validation |
 | 8 | Auth & Security | Wire authentication middleware, CORS, rate limiting |
 | 9 | Documentation | Generate API docs, Swagger UI config, example responses |
-| 10 | Deployment Config | Produce Wrangler TOML, Dockerfile, SAM template, or Railway config |
+| 10 | Deployment Config | Produce Wrangler TOML, Dockerfile, SAM template, Railway config, or Fly.io config |
 
 ## Phase-by-Phase Deep Dive
 
@@ -102,12 +102,12 @@ Convert an OpenAPI specification into a fully working, tested API server through
 
 ### Phase 10: Deployment Config
 
-**What it does:** Produces deployment configuration files matching the target platform. For Cloudflare Workers: `wrangler.toml` with D1 bindings. For Node.js: `Dockerfile` with multi-stage build and `docker-compose.yml`. For AWS Lambda: `template.yaml` (SAM with an API Gateway HTTP API), `samconfig.toml`, esbuild bundle config, and an OIDC-based deploy workflow. For Railway: `railway.toml` (Dockerfile build, health check, start command) and `nixpacks.toml`.
+**What it does:** Produces deployment configuration files matching the target platform. For Cloudflare Workers: `wrangler.toml` with D1 bindings. For Node.js: `Dockerfile` with multi-stage build and `docker-compose.yml`. For AWS Lambda: `template.yaml` (SAM with an API Gateway HTTP API), `samconfig.toml`, esbuild bundle config, and an OIDC-based deploy workflow. For Railway: `railway.toml` (Dockerfile build, health check, start command) and `nixpacks.toml`. For Fly.io: `fly.toml` (HTTP service, health check, Machine autoscaling).
 
 - **Inputs:** Project structure, database config, environment variables
-- **Outputs:** `wrangler.toml`, `Dockerfile` + `docker-compose.yml`, `template.yaml` + `samconfig.toml` + `esbuild.config.mjs`, or `railway.toml` + `nixpacks.toml`
+- **Outputs:** `wrangler.toml`, `Dockerfile` + `docker-compose.yml`, `template.yaml` + `samconfig.toml` + `esbuild.config.mjs`, `railway.toml` + `nixpacks.toml`, or `fly.toml`
 - **Tools:** `deployment-config-generator` skill
-- **Config:** `pipeline.config.json` -- `deployment.target` (cloudflare, node, aws-lambda, railway, both)
+- **Config:** `pipeline.config.json` -- `deployment.target` (cloudflare, node, aws-lambda, railway, fly, both)
 
 ## Configuration
 

diff --git a/package.json b/package.json
@@ -30,7 +30,8 @@
     "tdd",
     "cloudflare-workers",
     "aws-lambda",
-    "railway"
+    "railway",
+    "flyio"
   ],
   "author": "PAMulligan",
   "license": "MIT",