Skip to main content
Connect your Fly.io organization to enable CloudThinker agents to inventory apps, check machine run state and placement, and audit volume provisioning during an incident or a capacity review. Fly.io authenticates with a read-only organization token. The connection is read-only end to end: CloudThinker exposes no Fly.io action that changes your infrastructure, and Fly itself refuses to mutate anything with this token.

​
Prerequisites

  • A Fly.io organization containing the apps you want to inspect.
  • The flyctl CLI installed and signed in as a member of that organization.
  • A read-only organization token created from it.
A read-only token reads a single organization. If your apps span several organizations, create one token per organization and add one connection for each.

​
Setup

1

Create a read-only organization token

Run this in your terminal:
720h is 30 days. Pass --expiry deliberately: Fly.io tokens are valid for 20 years by default, and Fly’s own guidance is to use a shorter lifetime when practical.If you belong to more than one organization, name the one you want with --org <slug>.Copy the token the command prints.
2

Add the connection in CloudThinker

Navigate to Connections → Fly.io and enter:
  • Access token: the token you just created
Click Connect. CloudThinker verifies the token against Fly.io and shows a Connected status.
Copy the token when the command prints it. If you lose it, revoke that token and create a new one rather than trying to recover the value.

​
Connection details

CloudThinker resolves the organization from the token, so there is no organization slug or region to configure.

​
Required permissions

The token type is the permission model. fly tokens create readonly produces a token limited to reading a single organization and its resources — it cannot deploy, scale, restart, or destroy anything, and no additional scoping is needed or available.
Do not substitute fly tokens create org or a personal auth token. Both grant write access to your organization. The connection does not need it, and a read-only token is the barrier that makes an accidental change impossible at the provider rather than merely disallowed in CloudThinker.
Follow least privilege: keep the read-only token type, set a short --expiry, and revoke the token when the work it was created for is finished.

​
What this connection cannot reach

This connection reads the Fly.io control plane and nothing else. It cannot:
  • Change anything — no deploys, scaling, machine start/stop/restart, volume changes, secrets, or app creation and destruction. When a fix needs a write, the agent reports the fly command for you to run yourself.
  • Read logs or metrics — there is no log tail and no application telemetry here.
  • Read secrets or configuration — app secrets and environment values are never fetched.
  • Measure disk usage — volume size is provisioned capacity, never used capacity. Nothing reads a filesystem.
  • Report cost — Fly bills provisioned volume capacity, but the rate is not readable through this connection, so agents report GB and never a dollar figure.

​
Agent capabilities

Once connected, agents have read access to your Fly.io organization, apps, machines, volumes, and regions.
There are no approval-gated actions on this connection, because there are no actions. Every capability above is a read.

​
How to read the results

App status and machine state are Fly.io control-plane records, not application health checks. Three consequences are worth knowing before you act on a report:
  • A started machine is not proof that your app works. This connection does not check whether your app responds.
  • A stopped machine is not a fault. Fly stops machines that have autostop configured.
  • An unattached volume is still costing you. Fly charges for a volume whether or not a Machine is attached, and a volume becomes unattached only when its Machine is destroyed, not when it is stopped.
An app with no machines has never been deployed. A pending or not-deployed app is a reserved name, not a failure.

​
Verify the connection

​
Example prompts

Lists are capped by default and say how many rows they hid. Ask for a wider view when you need one.

​
Troubleshooting

The token is missing, invalid, or expired. Reissue it with fly tokens create readonly and update the connection.
The app name is wrong, or it belongs to an organization this token cannot read. Ask the agent to list your apps first and use a name from that list.
The read-only token does not cover that resource. Confirm the token was created for the organization that owns the app, and that its expiry has not passed.
A call was refused or unavailable, so the agent reports the gap instead of a number. This is not the same as a count of zero — treat that section as unknown rather than empty.
Expected. This connection is read-only by design. Ask the agent for the exact fly command and run it yourself.

​
Security

  • Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
  • Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
  • Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
  • Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.
  • Read-only at the provider — the token type Fly.io issues here cannot make changes, so the guarantee holds even if something asks it to.
  • Set a short expiry — Fly.io defaults tokens to 20 years. Always pass --expiry, and treat the default as a mistake rather than a convenience.
  • Revoke when finished — fly tokens revoke <token id> invalidates it. The Fly.io dashboard also lists organization tokens: choose the organization from the dropdown, then click Tokens.
  • One organization per token — a read-only token reads one organization, which keeps the blast radius of a leaked token to that organization alone.

Vercel Connection

Similar setup for another application hosting platform

Rancher Connection

Another read-only inventory and health connection