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

Agent setup

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 (do not paste the value in chat):

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. In the account secrets UI, approve hosts api.machines.dev and api.fly.io.
4. Share this listing as https://kody.codes/@kody/fly

Auth

API token (secret-backed). There is no Fly OAuth integration. Do not open /connect/oauth for Fly.

• Machines REST (api.machines.dev) uses Authorization: Bearer.
• GraphQL, app logs, and Prometheus (api.fly.io) use Bearer / FlyV1.

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". There are no hard-coded account aliases or organization slugs.

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.

Exports

• kody:@kody/fly — action dispatcher (defaults to smoke-test); also re-exports every helper below
• kody:@kody/fly/organizations — list or resolve organizations via GraphQL
• kody:@kody/fly/apps — list/get apps via Machines REST
• kody:@kody/fly/machines — list/get machines; start/stop/destroy with dryRun
• kody:@kody/fly/machine-count — count machines grouped by state and app
• kody:@kody/fly/app-machines — list machines for one app by appName or appId
• kody:@kody/fly/logs — fetch and summarize app logs for a time window
• kody:@kody/fly/metrics — Fly Prometheus instant/range queries and common app metrics
• kody:@kody/fly/graphql — custom GraphQL queries
• kody:@kody/fly/docs — API patterns and export discovery metadata
• kody:@kody/fly/smoke-test — dry-run self-check, then a live org/apps read when flyApiToken exists
• kody:@kody/fly/scheduled-status — no-argument machine-count wrapper used by the disabled job

Mutation safety

• Pass dryRun: true on startMachine, stopMachine, or destroyMachine to return { dryRun: true, method, path } without contacting Fly.
• destroyMachine also throws unless confirm: true.
• Do not destroy anyone's machines from a smoke test or scheduled job.

import { startMachine, destroyMachine } from 'kody:@kody/fly/machines'

const preview = await startMachine({
	appName: 'my-app',
	machineId: '148e26d9b3e089',
	dryRun: true,
})

const destroyed = await destroyMachine({
	appName: 'my-app',
	machineId: '148e26d9b3e089',
	confirm: true,
})

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.

Smoke test

import fly from 'kody:@kody/fly'

export default async function main() {
	return await fly()
}

Without flyApiToken this still returns { ok: true, live: false } plus the setup URL. With the secret saved it lists organizations and a sample of apps — no writes.

Example

import fly from 'kody:@kody/fly'

export default async function main() {
	return await fly({
		action: 'list-apps',
		organizationSlug: 'my-org',
	})
}

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.

Docs

• Machines API
• OpenAPI spec
• Access tokens