fly-io

Getting Started

1. Install the skill using the command above
2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
3. Reference the skill in your prompt
4. The AI will use the skill's capabilities automatically

Example Prompts

• "Deploy the latest build to the staging environment and run smoke tests"
• "Check the CI pipeline status and summarize any recent failures"

Overview

Fly.io deploys applications to Firecracker microVMs across 30+ edge regions worldwide, providing sub-50ms latency to users. It supports scale-to-zero machines, persistent NVMe volumes, LiteFS for multi-region SQLite replication, and private WireGuard networking between services.

Instructions

• When deploying applications, use fly launch to auto-detect the framework and generate a Dockerfile, then fly deploy for zero-downtime rolling updates with health checks.
• When configuring scaling, use auto_stop_machines and auto_start_machines in fly.toml to scale to zero when idle and wake on incoming requests, and set machine sizing appropriate to the workload.
• When managing multi-region deployments, use fly scale count --region to distribute machines, fly-replay header to route writes to the primary region, and LiteFS for SQLite read replicas.
• When handling persistent data, attach volumes for durable storage (machines are ephemeral), use LiteFS for multi-region SQLite, or Tigris for S3-compatible object storage.
• When connecting services, use .internal DNS for private service-to-service communication over the WireGuard mesh and never expose internal services to the public internet.
• When managing secrets, use fly secrets set KEY=value for encrypted secret storage accessible as environment variables.
• When troubleshooting, use fly logs for real-time streaming, fly ssh console to access running machines, and fly proxy to tunnel to internal services.

Examples

Example 1: Deploy a multi-region web application

User request: "Deploy my app globally with Fly.io in US, Europe, and Asia"

Actions:

1. Initialize with fly launch and configure Dockerfile
2. Deploy machines to three regions: fly scale count 2 --region iad,cdg,nrt
3. Set up LiteFS for SQLite replication across regions
4. Configure fly-replay header for write routing to the primary region

Output: A globally distributed app with read replicas in three regions and automatic write routing.

Example 2: Configure a cost-efficient staging environment

User request: "Set up a Fly.io staging environment that scales to zero when not in use"

Actions:

1. Create a staging app with fly launch
2. Configure auto_stop_machines = "stop" and auto_start_machines = true in fly.toml
3. Attach a volume for persistent database storage
4. Set health checks with appropriate timeouts for routing

Output: A staging environment that stops idle machines and wakes in sub-second on the next request.

Example 3: Canary deployment with auto-rollback

User request: "Deploy my app to Fly.io but test on one machine first. If the health check fails, roll back."

Actions:

1. Deploy with --strategy canary to spin up a single new machine
2. Health check the canary machine at the app's health endpoint
3. If healthy, promote with fly deploy --strategy rolling to replace all machines
4. If unhealthy, rollback with fly releases rollback

#!/bin/bash
# deploy-canary.sh — Fly.io canary deployment with auto-rollback
set -euo pipefail

APP="${1:?Usage: deploy-canary.sh <app-name>}"
HEALTH_PATH="${2:-/api/health}"

echo "🐤 Deploying canary..."
fly deploy --app "$APP" --strategy canary --wait-timeout 120

HEALTH_URL="https://${APP}.fly.dev${HEALTH_PATH}"
HEALTHY=false
DEADLINE=$((SECONDS + 60))

while [ $SECONDS -lt $DEADLINE ]; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_URL" || true)
  [ "$STATUS" = "200" ] && HEALTHY=true && break
  sleep 3
done

if [ "$HEALTHY" = true ]; then
  echo "✅ Canary healthy! Promoting..."
  fly deploy --app "$APP" --strategy rolling
  echo "🎉 Production deploy complete"
else
  echo "❌ Canary failed! Rolling back..."
  fly releases rollback --app "$APP"
  echo "⏪ Rolled back"
  exit 1
fi

Guidelines

• Use auto_stop_machines = "stop" for dev/staging to save costs; machines stop after idle timeout.
• Keep auto_start_machines = true so machines wake on incoming requests with sub-second cold start.
• Use .internal DNS for service-to-service calls; never expose internal services publicly.
• Store persistent data on volumes, not the machine filesystem, since machines are ephemeral.
• Use LiteFS for SQLite apps needing multi-region reads; it is simpler than PostgreSQL replication.
• Set health checks with realistic timeouts; Fly Proxy uses them for routing, not just monitoring.
• Use fly-replay header for write operations in multi-region setups to route to the primary region.