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.
• breaking Python packages in `requirements.txt` or `pyproject.toml` may specify a minimum Python version. If the deployment environment (e.g., `fly.toml` buildpack settings, Dockerfile base image) uses an older Python version, package installation will fail with 'Requires-Python' errors.
  Fix: Ensure the Python version used in your deployment environment (e.g., specified in `fly.toml` buildpack, or your Dockerfile's `FROM` image) meets the minimum `Requires-Python` version of your dependencies. For example, if a dependency requires `Python >=3.11`, use `python:3.11-slim` or newer.
• gotcha Test output shows pip warnings regarding running as the 'root' user and an available update. Running pip as root can cause permission issues, and an outdated pip might lead to unexpected behavior or missed features.
  Fix: For the 'root' user warning, ensure pip is run within a virtual environment or specify a non-root user in your Dockerfile (e.g., using a `USER` instruction). For the pip update notice, run `pip install --upgrade pip` to update pip.

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