Fly.io (flyctl + Machines API)

Warnings

• breaking Apps V1 (Nomad-based) was fully removed March 2023. All apps migrated to V2 (Machines). Old fly.toml files using legacy [[services]] format may need updating to [http_service] for simple HTTP apps.
  Fix: Use [http_service] for single-process HTTP apps. Use [[services]] only for TCP or multi-port configurations. Run fly config validate to check.
• breaking auto_stop_machines previously accepted boolean true/false. Now requires string values: 'off', 'stop', or 'suspend'. Boolean true still maps to 'stop' but causes a deprecation warning and will eventually break.
  Fix: Replace auto_stop_machines = true with auto_stop_machines = 'stop' or 'suspend'.
• breaking Free tier removed for new organizations created after October 7, 2024. New accounts are pay-as-you-go only. Existing users keep legacy free allowances unless they switch plans.
  Fix: Use auto_stop_machines = 'suspend' + min_machines_running = 0 to minimize cost on low-traffic apps. Stopped/suspended machines only billed for storage (~$0.15/GB/month).
• gotcha fly launch creates two Machines by default on first deploy if [http_service] is configured (redundancy by default). This doubles cost unexpectedly for hobby projects.
  Fix: Run fly scale count 1 after first deploy, or set min_machines_running = 0 with auto_stop_machines = 'suspend'.
• gotcha Apps must listen on 0.0.0.0:<internal_port>, not 127.0.0.1 or localhost. Listening on localhost causes 'app is not listening on the expected address' deploy warning and the app is unreachable.
  Fix: Bind your server to 0.0.0.0. E.g. uvicorn app:app --host 0.0.0.0 --port 8080
• gotcha Machine suspend (auto_stop_machines = 'suspend') requires ≤2GB RAM, no swap configured, no GPU, and no schedule. Machines not meeting requirements silently fall back to 'stop' behavior.
  Fix: Verify requirements before relying on suspend for fast cold-start. Check fly machine status <id> to confirm state transitions.
• gotcha fly.toml changes do not take effect until fly deploy is run. Saving fly.toml does not trigger a redeploy. Dashboard view of fly.toml may lag behind actual deployed config.
  Fix: Always run fly deploy after any fly.toml change. Use fly config show to inspect deployed config.
• gotcha flyctl auto-updates by default. New flyctl versions occasionally change behavior or add new fly.toml schema fields that conflict with old configs. Pinning flyctl version in CI is recommended.
  Fix: In GitHub Actions use superfly/flyctl-actions@v1 pinned to a specific version. Disable autoupdate in production environments with fly settings autoupdate disable.

Install

• curl -L https://fly.io/install.sh | sh flyctl CLI (macOS/Linux)
• brew install flyctl flyctl CLI (Homebrew)
• pip install fly-python-sdk Unofficial Python SDK (third-party, unmaintained — avoid)

Imports

• Machines API (Python)

  import requests
  
  headers = {"Authorization": f"Bearer {FLY_API_TOKEN}"}
  requests.get("https://api.machines.dev/v1/apps/{app_id}/machines", headers=headers)

  No official Python SDK exists. Use the Machines REST API directly with any HTTP client.

Quickstart

Primary workflow is CLI-based. fly launch detects framework and generates fly.toml. fly deploy on every code change.

# Deploy a Python app:
# 1. In your project directory:
fly launch          # Scans project, creates fly.toml, provisions app
fly deploy          # Builds image, deploys to Machines

# Minimal fly.toml for a Python web app:
# app = 'my-app'
# primary_region = 'iad'
#
# [http_service]
# internal_port = 8080
# force_https = true
# auto_stop_machines = 'suspend'
# auto_start_machines = true
# min_machines_running = 0
#
# [[vm]]
# memory = '256mb'
# cpu_kind = 'shared'
# cpus = 1

# Secrets (env vars):
fly secrets set OPENAI_API_KEY=sk-...

# Scale:
fly scale count 2
fly scale memory 512