LEARN / FLYCTL, MACHINES API, TOKENS

Automation: flyctl, the Machines API, tokens and MCP

Fly.io is a CLI-first platform: flyctl does everything, the Machines REST API is the lower-level path for custom orchestration, and tokens are macaroons you can scope down to one app or one command. There is no Terraform provider, and Fly.io says that is intentional (https://docs.fly.io/blueprints/infra-automation-without-terraform/).

Install. Homebrew on macOS is brew install flyctl; the install script curl -L https://fly.io/install.sh | sh works on macOS and Linux; Windows uses a PowerShell script (https://docs.fly.io/flyctl/install/).
Sign in. fly auth signup and fly auth login are the two entry points (https://docs.fly.io/flyctl/). Login is browser-based by default, with email/password and one-time-password options (https://docs.fly.io/flyctl/cmd/fly_auth_login/).
The core commands. fly launch creates an app, fly deploy ships it, and fly secrets, fly logs, fly status, fly releases, fly ips and fly certs cover day two (https://docs.fly.io/flyctl/).

fly launch and fly deploy

fly launch is run from the project’s source directory. For most languages and frameworks it generates a Dockerfile and usually a .dockerignore, and you edit and commit that Dockerfile yourself (https://docs.fly.io/launch/create/). Framework scanners are strongest for Elixir/Phoenix, Laravel, Rails and Django (https://docs.fly.io/launch/create/). fly launch --no-deploy creates the app and fly.toml without releasing (https://docs.fly.io/launch/deploy/).

fly deploy builds or fetches the image, then updates Machines as a group using the local fly.toml (https://docs.fly.io/launch/deploy/). Facts a support engineer needs:

Topic	What the docs say
Image choice	`--image` or `[build]` in `fly.toml` wins over any Dockerfile; then the `[build]` method; then `--dockerfile`; then a `Dockerfile` in the working directory (https://docs.fly.io/launch/deploy/)
First deploy	With no process groups defined, the first deployment gives two Machines for process groups with services, one Machine when a volume is mounted, and one started plus one stopped standby Machine for groups without services (https://fly.io/docs/launch/deploy/, https://fly.io/docs/apps/app-availability/)
Strategies	`rolling` (default), `immediate`, `canary`, `bluegreen` (https://docs.fly.io/launch/deploy/)
Release command	A one-off command in a temporary VM before release, good for migrations, with no access to mounted volumes (https://docs.fly.io/launch/deploy/)
Builds	Remote by default; `--local-only` uses local Docker; `--image` skips building; `--buildkit` is experimental (https://docs.fly.io/flyctl/integrating/)

Say: “Setting a secret restarts your Machines.” The docs state that fly secrets set triggers a new deployment, and --stage defers it (https://docs.fly.io/launch/deploy/, https://docs.fly.io/apps/secrets/).

Tokens and scopes

Fly.io access tokens are macaroons with predefined scopes, from org-wide down to running one command on one app’s Machines (https://docs.fly.io/security/tokens/).

Command	Scope	Source
`fly tokens create deploy`	One app; the default for CI	https://docs.fly.io/flyctl/integrating/
`fly tokens create org`	Every app in one organization	https://docs.fly.io/security/tokens/
`fly tokens create readonly`	Read-only across one org	https://docs.fly.io/flyctl/integrating/
`fly tokens create ssh`	SSH to one app (also allowed on the org WireGuard network)	https://docs.fly.io/security/tokens/
`fly tokens create machine-exec`	Only the command you name, via `--command`	https://docs.fly.io/flyctl/integrating/

Expiry. “Tokens are valid for 20 years (175200h0m0s) by default.” Set --expiry (or -x) to the shortest duration that works (https://docs.fly.io/security/tokens/).
Do not use the login token in CI. The docs say the fly auth token output is “no longer” the right API token for everything, and call it deprecated and hidden (https://docs.fly.io/security/tokens/, https://docs.fly.io/flyctl/integrating/).
Env vars. FLY_API_TOKEN skips interactive auth and beats a saved login; FLY_ACCESS_TOKEN is an alternative name that wins if both are set; FLY_APP names the target app (https://docs.fly.io/flyctl/integrating/).
Machine identity. POST /v1/tokens/oidc returns an OpenID Connect JWT for a Machine, with the aud claim you set (https://docs.fly.io/machines/api/tokens-resource/).

CI/CD with GitHub Actions

The documented path is: create a deploy token, store it as the repository secret FLY_API_TOKEN, and run superfly/flyctl-actions/setup-flyctl then flyctl deploy --remote-only (https://docs.fly.io/launch/continuous-deployment-with-github-actions/). The same flyctl docs show a monorepo matrix using FLY_APP and a staging-on-push, production-on-release pattern (https://docs.fly.io/flyctl/integrating/). For GitLab CI, CircleCI, Jenkins or Buildkite the setup is the same three steps: install flyctl, set FLY_API_TOKEN, run commands (https://docs.fly.io/flyctl/integrating/).

Infrastructure as code

“Fly.io has no Terraform provider” is the blueprint’s own description, and it recommends flyctl plus GitHub Actions for most users (https://docs.fly.io/blueprints/infra-automation-without-terraform/). A 2022 changelog entry says an official Terraform provider was released (https://fly.io/blog/logbook-2022-06-01/); treat the current docs as the answer and the old post as history. Scripts of flyctl commands are “linear and imperative, not declarative or idempotent” (https://docs.fly.io/blueprints/infra-automation-without-terraform/). Pulumi: not in the corpus [verify].

The Machines REST API

Base URLs. Public https://api.machines.dev; internal http://_api.internal:4280 from inside your private WireGuard network (https://docs.fly.io/machines/api/working-with-machines-api/).
Auth. Authorization: Bearer <fly_api_token> on every request; fly tokens deploy mints a token for the app in your current directory (https://docs.fly.io/machines/api/working-with-machines-api/).
Resources. Apps, Machines, Volumes, Certificates and Tokens, plus an OpenAPI 3.0 spec; fly-go is the Go client flyctl is built on (https://docs.fly.io/machines/api/).
Rate limits. “1 request, per second, per action”, bursting to 3 req/s; Get Machine allows 5 req/s with a burst of 10; app deletions are capped at 100 per minute (https://docs.fly.io/machines/api/working-with-machines-api/).
Create a Machine. POST /v1/apps/{app_name}/machines boots by default; skip_launch creates without booting. Creation can fail on capacity, so you must handle retry or another region (https://docs.fly.io/machines/api/machines-resource/).
Leases and metadata. A lease nonce goes in the fly-machine-lease-nonce header; metadata has its own GET, POST and DELETE endpoints, and GET /machines?metadata.foo=bar filters (https://docs.fly.io/machines/api/machines-resource/).
Fly-Replay. An app answers with a fly-replay header and Fly Proxy replays the request to a region, instance, app or prefer_instance (https://docs.fly.io/networking/dynamic-request-routing/).

MCP and agent skills

Run MCP servers on Fly. fly mcp launch "uvx mcp-server-time" --claude --server time deploys a stdio server to a Machine and configures the client; bearer auth is on by default (https://docs.fly.io/model-context-protocol/launch/). All fly mcp subcommands are marked experimental (https://docs.fly.io/flyctl/cmd/fly_mcp/).
flyctl’s local MCP server. fly mcp server --claude (also Cursor, Neovim, VS Code, Windsurf, Zed) exposes apps, certs, logs, machine, orgs, platform, secrets, status and volumes (https://docs.fly.io/model-context-protocol/flyctl-server/).
Hosted Fly MCP. https://mcp.fly.io signs in with browser OAuth; you pick organizations, apps and Sprites permissions on one consent screen, with no pasted token (https://mcp.fly.io/guide.md). Per its tool reference, it covers apps, Machines, volumes, secrets, Managed Postgres and Sprites; deployment workflows, app creation and org administration are not included, and Managed Postgres tools never delete or return passwords (https://mcp.fly.io/guide.md).
Agent skills. fly skills install writes the fly and brand skills from superfly/skills into each detected agent’s skills directory (https://docs.fly.io/model-context-protocol/agent-skills/). fly setup agent installs the skills and adds the MCP entry in one step; it needs a flyctl release after v0.5.1 (https://docs.fly.io/model-context-protocol/setup-agent/).

Lead with: “Use a deploy token in CI, a readonly token for dashboards, and the hosted MCP when an agent only needs to look.”

← Proxy, networking, domains, TLS · Data and integrations →