Fly.io

Clanker supports querying and managing Fly.io apps, machines, volumes, secrets, and addons through the Fly.io Machines REST API + the legacy GraphQL endpoint. The flyctl CLI is required only for deploys, SSH console, scaling, and secrets set (which pipes values over stdin so they never appear on the command line).

---

Authentication

Fly.io authentication uses a personal API token.

Obtaining a token

1. Run flyctl auth token if you already have flyctl signed in, or
2. Visit fly.io/dashboard/personal/tokens and create a new token with the scopes you need.

Token strings typically begin with fo1_…. Treat them like any credential — they grant access to every org the token's owner can see.

---

Configuration

Add your API token to ~/.clanker.yaml:

flyio:
  api_token: "fo1_xxxxxxxxxxxx"
  org_slug: ""              # optional — filter to one org

Alternatively, set an environment variable:

export FLY_API_TOKEN="fo1_xxxxxxxxxxxx"
export FLY_ORG="personal"   # optional

Token resolution order

1. flyio.api_token in the config file
2. FLY_API_TOKEN environment variable
3. FLY_ACCESS_TOKEN environment variable

Org slug resolution order

1. flyio.org_slug in the config file
2. FLY_ORG environment variable
3. FLY_ORG_SLUG environment variable

Note: Org slug is a filter, not a scope. A Fly token can see resources across every org it has access to. Leaving the slug empty (the default) returns resources from every visible org. Set it to filter list views to one org.

---

Prerequisites

The flyctl CLI (also aliased as fly) must be on your PATH for deploys, scaling, SSH console, and secrets set operations. Read-only queries against apps, machines, volumes, IPs, certs, releases, regions, and addons do not require flyctl — Clanker uses the REST + GraphQL APIs directly.

# macOS
brew install flyctl

# Linux / WSL
curl -L https://fly.io/install.sh | sh

# Windows (PowerShell)
iwr https://fly.io/install.ps1 -useb | iex

Verify the install:

flyctl version
flyctl auth whoami

---

Querying Fly.io

Explicit --flyio flag

clanker ask --flyio "what apps are running and in which regions?"
clanker ask --flyio "which machines are using the most memory?"
clanker ask --flyio "do I have any unattached volumes?"

Conversation history is preserved per-org at ~/.clanker/conversations/flyio_<slug>.json, so follow-ups stay in context.

Automatic routing

When a fly.toml is present in the working directory, Clanker's deploy analyzer picks up Fly.io as a candidate target automatically. Keyword-based routing on phrases like fly, flyctl, machine, fly.io app is also enabled in clanker ask for hands-free use.

---

Supported services

Clanker covers the full Fly.io surface across the Machines REST API and the legacy GraphQL endpoint:

Service	Operations	Backed by
Apps	list, get, create, destroy, restart	REST
Machines	list, get, start, stop, restart, suspend, destroy, clone, cordon, uncordon, exec	REST + flyctl for exec
Volumes	list, create, destroy, extend, fork, snapshots	REST
Secrets	list (names + digests only), set, unset, deploy	flyctl (values piped via stdin, never logged)
IPs	list, allocate (v4 / v6 / shared / private), release	REST
Certificates	list, add, check, remove	REST
Releases	list, rollback	REST
Scale	count, vm preset, memory, cpu	flyctl
Postgres	list (managed + unmanaged), create, attach, detach, failover, backups	flyctl + GraphQL
Managed Postgres (MPG)	list, create, destroy	REST
Redis (Upstash)	list, create, destroy	GraphQL addons
Tigris (object storage)	list, create bucket, destroy	GraphQL addons
MySQL	list (preview)	GraphQL addons
Regions	list	REST
Organizations	list, get, members, current user	GraphQL
Tokens	list, revoke	GraphQL
WireGuard	list peers, create, remove	GraphQL
Extensions	list (Sentry, Tigris, Redis, etc.)	GraphQL
Logs	snapshot (REST), --follow stream	flyctl subprocess
Deploy	deploy, redeploy, rollback	flyctl

---

Static commands

Direct REST/GraphQL queries without AI interpretation:

# Apps + machines + volumes
clanker fly list apps
clanker fly list machines --app my-app
clanker fly list volumes --app my-app
clanker fly get app my-app
clanker fly get machine 1234abcd --app my-app

# Machine lifecycle
clanker fly restart machine 1234abcd --app my-app
clanker fly stop 1234abcd --app my-app
clanker fly start 1234abcd --app my-app
clanker fly destroy machine 1234abcd --app my-app --force

# Secrets (names + digests only; values never echoed)
clanker fly list secrets --app my-app
clanker fly secrets set DATABASE_URL=... --app my-app
clanker fly secrets unset OLD_KEY --app my-app
clanker fly secrets deploy --app my-app

# Networking
clanker fly list ips --app my-app
clanker fly ips allocate --app my-app --type v4
clanker fly list certs --app my-app
clanker fly certs add example.com --app my-app

# Addons
clanker fly list postgres
clanker fly list redis
clanker fly list tigris
clanker fly list extensions

# Platform
clanker fly list regions
clanker fly list orgs
clanker fly auth whoami

Add --raw to any command for unformatted JSON output suitable for piping to jq.

---

Deploy + scale

These shell out to flyctl because Fly's deploy pipeline is image-build-aware:

# Deploy from the working directory
clanker fly deploy --app my-app --region iad
clanker fly deploy . --app my-app --strategy rolling

# Adjust scale
clanker fly scale count 3 --app my-app
clanker fly scale vm performance-2x --app my-app
clanker fly scale memory 2048 --app my-app

# Roll back to the previous stable release
clanker fly rollback --app my-app

---

Maker pipeline

Generate AI-authored plans for Fly.io changes:

# Generate a plan
clanker ask --flyio --maker "create a 512MB shared-cpu-1x machine in iad for my-app"

# Apply an approved plan
clanker ask --apply --plan-file plan.json

# Allow destructive operations
clanker ask --flyio --maker --destroyer "destroy the staging machine"

The maker validator blocks destructive flyctl commands without --force, blocks flyctl auth logout, and pipes stdin for flyctl secrets set so values are never echoed back through the LLM.

---

Backend credentials

If you're using the Clanker backend credential store, store your Fly.io token under the flyio provider:

clanker credentials store flyio --api-token "fo1_xxxxxxxxxxxx" --org-slug "personal"

The CLI falls back to the backend store when neither flyio.api_token nor FLY_API_TOKEN is set locally.

---

Desktop app

The Clanker Cloud desktop app exposes Fly.io as a first-class provider:

• Onboarding wizard — Fly.io step validates your token and offers an org-slug picker.
• Profile settings — paste a token + optional org filter; values persist locally in SQLite.
• Infrastructure scan — apps, machines, volumes, IPs, certificates, postgres clusters, redis instances, and Tigris buckets are pulled into the unified resource graph alongside AWS/GCP/Cloudflare resources.
• Fly.io window — per-tab views for Apps / Machines / Volumes / Secrets / Networking / Storage / Releases / Logs / Regions, with per-row actions (start/stop/restart/suspend/destroy/clone) and a confirmation modal for destructive ops.
• Log streaming — the backend shells flyctl logs --app X and proxies stdout as Server-Sent Events. Requires flyctl on the host's PATH; you'll see an "Install flyctl to enable log streaming" hint when it's missing.