> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fly.io

> Connect Fly.io to CloudThinker for read-only app, machine, volume, and region inventory across an organization

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.

<Info>
  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.
</Info>

***

## Setup

<Steps>
  <Step title="Create a read-only organization token">
    Run this in your terminal:

    ```bash theme={null}
    fly tokens create readonly --name cloudthinker --expiry 720h
    ```

    `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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

***

## Connection details

| Field                  | Description                                                                          | Example |
| ---------------------- | ------------------------------------------------------------------------------------ | ------- |
| **FLY\_ACCESS\_TOKEN** | Read-only Fly.io organization token for the organization CloudThinker should inspect | —       |

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

***

## 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.

<Warning>
  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.
</Warning>

<Tip>
  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.
</Tip>

***

## 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.

| Capability        | Description                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Organizations** | List the organizations the token can read, by slug and name                                                                                           |
| **Apps**          | List apps with their status, owning organization, and whether they are deployed                                                                       |
| **Machines**      | Per app, list machine ID, name, state, region, and last update, with a count of each state, how many are not started, and how many regions are in use |
| **Volumes**       | Per app, list volume ID, name, size, region, state, attachment, and encryption, with unattached volume and GB totals and total provisioned GB         |
| **Regions**       | Count the regions available for placement, excluding deprecated ones                                                                                  |

<Info>
  There are no approval-gated actions on this connection, because there are no actions. Every capability above is a read.
</Info>

### 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.

<Note>
  An app with no machines has never been deployed. A pending or not-deployed app is a reserved name, not a failure.
</Note>

### Verify the connection

```text theme={null}
@alex check the Fly.io connection and list my organizations and apps
```

### Example prompts

```text theme={null}
@alex list my Fly.io apps with their status and deployment state and #report as a table
@alex is my Fly.io app healthy — show the machine states and regions and #recommend what to check next
@alex audit Fly.io volumes for my app and #report unattached volumes and total provisioned GB
@alex which regions are my Fly.io machines running in, and how many regions could I place in
```

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

***

## Troubleshooting

<Accordion title="Error: You must be authenticated to view this">
  The token is missing, invalid, or expired. Reissue it with `fly tokens create readonly` and update the connection.
</Accordion>

<Accordion title="Error: Could not find App">
  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.
</Accordion>

<Accordion title="Insufficient permissions or 403 on a list call">
  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.
</Accordion>

<Accordion title="A section reports that it is unmeasured">
  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.
</Accordion>

<Accordion title="The agent refuses to deploy, scale, or restart">
  Expected. This connection is read-only by design. Ask the agent for the exact `fly` command and run it yourself.
</Accordion>

***

## 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.

***

## Related

<CardGroup cols={2}>
  <Card title="Vercel Connection" icon="https://mintcdn.com/cloudthinker/R1-llSMEloTP_DJf/images/icons/vercel.svg?fit=max&auto=format&n=R1-llSMEloTP_DJf&q=85&s=84c091b1a241ec5c1eaf822e2f155691" href="/guide/connections/vercel" width="24" height="24" data-path="images/icons/vercel.svg">
    Similar setup for another application hosting platform
  </Card>

  <Card title="Rancher Connection" icon="https://mintcdn.com/cloudthinker/fJM2cOggET3WD6Z_/images/icons/rancher.svg?fit=max&auto=format&n=fJM2cOggET3WD6Z_&q=85&s=49464037ea7c8bf7eac84e9e3c16ed43" href="/guide/connections/rancher" width="24" height="24" data-path="images/icons/rancher.svg">
    Another read-only inventory and health connection
  </Card>
</CardGroup>