@kody/fly

@kody/fly

Intent

Official Fly.io helpers so Kody agents can inspect the caller's organizations, apps, Machines, logs, and Prometheus metrics — not a shared platform org. Auth is a saved API token, not OAuth. Reads are free-form. Machine start, stop, and destroy support dryRun: true; destroy also requires confirm: true.

This listing is meant to be forked. After you fork, save your own flyApiToken and call the helpers in your account. No Fly app names or organization slugs are baked into the package.

Share this listing as https://kody.codes/@kody/fly

What it does

• List or resolve organizations via GraphQL
• List/get apps and Machines via Machines REST
• Start/stop/destroy Machines with dryRun (destroy also needs confirm: true)
• Count machines grouped by state and app; list machines for one app
• Fetch and summarize app logs; query Fly Prometheus metrics
• Run custom GraphQL queries

Prerequisites / setup

API token (secret-backed). There is no Fly OAuth integration. Do not open /connect/oauth for Fly. Never paste the token into chat. Agents: see AGENTS.md for import paths, smoke, and mutation guards.

1. Create a token at fly.io/dashboard → Account → Access Tokens. A read token is enough for apps, Machines, logs, and metrics. Start/stop/destroy need a token that can mutate Machines.
2. Save it in Kody:

https://kody.codes/account/secrets/new?name=flyApiToken&description=Fly.io%20API%20token%20for%20Machines%2C%20GraphQL%2C%20logs%2C%20and%20Prometheus&allowedHosts=api.machines.dev,api.fly.io&scope=user

3. Approve hosts api.machines.dev and api.fly.io.

Hosts

• api.machines.dev — Machines REST (apps, Machines, token info, mutations)
• api.fly.io — GraphQL, app logs, Prometheus

Multi-account

Pass account: "work" to use secret flyApiToken-work. Or pass secretName: "flyApiToken-staging".

https://kody.codes/account/secrets/new?name=flyApiToken-work&description=Fly.io%20API%20token%20for%20the%20work%20account&allowedHosts=api.machines.dev,api.fly.io&scope=user

When organizationSlug is omitted, the package lists organizations visible to the token: one org is used automatically; multiple orgs require an explicit slug.

Jobs

The machine-status job is declared disabled. It is a no-argument wrapper around scheduled-status (read-only machine counts). Enable it only after you confirm the token, hosts, and organization slug you want it to use.

Done when

• flyApiToken is saved; hosts api.machines.dev and api.fly.io are approved
• Smoke test returns { ok: true } (live: false before credentials; org/apps sample when the secret exists — no writes)
• Machine destroy refuses unless confirm: true; dryRun: true never contacts Fly

Branding

community-icon.svg is Fly.io's official brandmark (Simple Icons flydotio, approved by Fly.io, CC0) on Fly navy #24175B. Fly.io® is a trademark of Fly.io, Inc. This package is not affiliated with or endorsed by Fly.io.

Keep LICENSE (MIT), ## Intent, and community-icon.svg intact for community listing.

Docs

• Machines API
• OpenAPI spec
• Access tokens