Fly.io Machines & Apps
When a Fly.io app misbehaves, see which Machines are running in which region, read a Machine's recent events and exit codes, then start, stop or restart it and wait until it reaches the state you expect.
Connect this API to an AI agent Browse all specs
What you can do with Fly.io Machines & Apps via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v1/apps |
listApps | List the apps in an organization |
| GET | /v1/apps/{app_name} |
getApp | Get an app's details and status |
| GET | /v1/apps/{app_name}/machines |
listMachines | List the Machines of an app, optionally by region or state |
| GET | /v1/orgs/{org_slug}/machines |
listOrgMachines | List Machines across all apps in an organization |
| GET | /v1/apps/{app_name}/machines/{machine_id} |
getMachine | Get one Machine with its state, region and config |
| GET | /v1/apps/{app_name}/machines/{machine_id}/events |
listMachineEvents | List a Machine's recent events (starts, stops, exits) |
| GET | /v1/apps/{app_name}/machines/{machine_id}/wait |
waitForMachineState | Wait until a Machine reaches a given state |
| POST | /v1/apps/{app_name}/machines/{machine_id}/start |
startMachine | Start a stopped Machine |
| POST | /v1/apps/{app_name}/machines/{machine_id}/stop |
stopMachine | Stop a running Machine |
| POST | /v1/apps/{app_name}/machines/{machine_id}/restart |
restartMachine | Restart a Machine |
| GET | /v1/platform/regions |
listRegions | List Fly.io regions and their capacity |
Authentication
FlyBearerAuth
Bearer token — sent as Authorization: Bearer <token>
A Fly.io API token, sent as Authorization: Bearer <token>.
How to get a credential
- Install flyctl and sign in (
fly auth login). - Create an organization token:
fly tokens create org -o <org-slug>(covers every app in the org), or a deploy token for one app:fly tokens create deploy -a <app-name>. - Or open the Fly.io dashboard > Tokens and create a token there.
- Copy the whole token, including the
FlyV1prefix if it has one.
Permissions used
| Token | Operations |
|---|---|
| Org token | listApps, listOrgMachines, and everything below for any app in the org |
| Org or deploy token for the app | getApp, listMachines, getMachine, listMachineEvents, waitForMachineState, startMachine, stopMachine, restartMachine |
| Any valid token | listRegions |
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Token missing, expired or revoked | Create a new token with fly tokens create. |
| 403 | The token does not cover this app or org | Use an org token, or a deploy token for this app. |
| 400 | Invalid parameter, e.g. a wrong state or timeout value |
Read the error field and fix the value. |
| 429 | Rate limited | Wait a second and retry; avoid tight polling loops (use waitForMachineState). |
Store the token as a Bearer credential in VX Agents; never paste it into chat.
Usage guide
Setup
- Credential: a Fly.io token as a Bearer credential (
fly tokens create org -o <org-slug>for a whole organization, orfly tokens create deploy -a <app>for one app). - Worth pinning:
org_slugonlistApps/listOrgMachines(your org slug, orpersonal), andapp_nameif the agent should only touch one app.
Check and recover an app
listAppswithorg_slugto find the app, thengetAppfor its status.listMachinesfor the app; filter withstate(started,stopped,suspended, ...) orregion, and passsummary=trueto skip the full config.listOrgMachinesdoes the same across every app in the org (addupdated_afterto see recent changes).getMachinefor one Machine's state, region, image and checks;listMachineEvents(up to 50) shows recent starts, stops and exit codes, which usually explains a crash loop.- Ask the user before changing anything, then
stopMachine,startMachineorrestartMachine(optionalsignalandtimeout). waitForMachineStatewithstate=started(orstopped) andtimeout(seconds, default 60) instead of pollinggetMachine.listRegionslists region codes (e.g.ams,iad,syd) to explain where Machines run.
Good to know
- Machine ids are 14-character hex strings, e.g.
3d8d9ed1b12389; app names are the names shown byfly apps list. listMachinesreturns at mostlimititems (up to 1000); continue with thefly-next-cursorresponse header ascursor.listAppspages withnext_cursor.- Timestamps are RFC 3339 (
updated_after=2026-10-01T00:00:00Z). - Stopping or restarting a Machine takes that instance offline: always confirm with the user first. Creating, destroying and exec on Machines, secrets and Postgres admin are not part of this spec.
Source: Fly.io Machines API reference (https://fly.io/docs/machines/api/), checked 2026-10-22.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Fly.io Machines & Apps” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.