🎯

fly-io

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill fly-io

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/fly-io
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/fly-io/
  • All projects ~/.claude/skills/fly-io/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert Fly.io assistance covering fly.toml, global app distribution, persistent volumes, Machines API, and scaling. Use when deploying full-stack apps and databases close to users globally.

Fly.io

Fly.io transforms containers into Firecracker MicroVMs running on bare metal across the globe. It is essentially a "CDN for your backend".

When to Use

  • Global Edge Microservices & APIs: Deploying full-stack applications and databases physically close to users.
  • Modern Full-Stack Frameworks: Next.js, Remix, Phoenix LiveView, Rails, and Node.js with instant global scaling.
  • LiteFS Distributed SQLite: Replicating SQLite databases globally with low-latency local reads and streaming primary writes.
  • GPU Inference at the Edge: Running open-weight AI models on edge GPUs with rapid cold starts.

Quick Start

fly launch
# Scans source code, creates Dockerfile, creates fly.toml

fly deploy
# fly.toml
app = "my-app"
primary_region = "iad"

[http_service]
  internal_port = 8080
  force_https = true

Core Concepts

Declarative Configuration with fly.toml

Defining machine resources, scaling rules, and health checks:

# fly.toml
app = "api-edge-service"
primary_region = "ord" # Chicago primary

[build]
  dockerfile = "Dockerfile"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = 'stop'   # Scale to zero when idle
  auto_start_machines = true
  min_machines_running = 1

  [http_service.concurrency]
    type = "requests"
    soft_limit = 200
    hard_limit = 250

[[vm]]
  size = "shared-cpu-2x"
  memory = "2048mb"

[[services.http_checks]]
  interval = "10s"
  timeout = "2s"
  grace_period = "5s"
  method = "get"
  path = "/healthz"

Global SQLite Replication with LiteFS

Configuring distributed SQLite clusters with automated failover:

# etc/litefs.yml
fuse:
  dir: "/litefs"

data:
  dir: "/var/lib/litefs"

exit-on-error: false

proxy:
  addr: ":8080"
  target: "localhost:8081"
  db: "production.db"

lease:
  type: "consul"
  advertise-url: "http://${FLY_ALLOC_ID}.vm.${FLY_APP_NAME}.internal:20202"
  candidate: ${FLY_REGION == "ord"} # Only Chicago is eligible for primary

Fly CLI (flyctl) Deployment Workflows

Deploying and scaling applications across geographic regions:

# Launch app from current directory
fly launch --no-deploy

# Deploy container image to edge fleet
fly deploy

# Scale application to multiple global regions
fly scale count 3 --region ord,fra,sin

# Inspect status of running Fly Machines
fly status
fly logs

Common Patterns

Persistent Volume with Multi-Region Machine Configuration

Problem: Stateful databases on ephemeral serverless platforms lose disk data when scaled.

Solution: Attach persistent Fly volumes in fly.toml:

app = "my-sqlite-db"
primary_region = "ord"

[mounts]
  source = "data_vol"
  destination = "/data"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 1

Provision volume: fly volumes create data_vol --region ord --size 10

Best Practices

Do:

  • Set auto_stop_machines = 'stop' and auto_start_machines = true to reduce costs on low-traffic endpoints.
  • Deploy in regions closest to your primary database or users to minimize latency.
  • Use persistent Fly Volumes (fly volumes create) for services requiring local storage.
  • Use fly secrets set to encrypt and inject environment variables securely.

Don't:

  • Commit sensitive environment secrets into fly.toml.
  • Run multi-node primary-write databases without LiteFS or managed PostgreSQL clusters.
  • Neglect health checks; Fly requires passing checks to route HTTP traffic to instances.

Troubleshooting

ErrorCauseSolution
Error: could not find an instance of app ... in regionApp has no running Machines deployed in the targeted region.Deploy machines with fly scale count 2 --region ord.
Machine crashed with exit code 137Process exceeded allocated Machine RAM (OOM killed).Increase machine RAM: fly scale memory 1024.
Health check failing on /healthApplication took longer to boot than configured grace_period.Increase grace_period = "30s" in fly.toml.

References

More from this repository10