@kody/fly

@kody/fly — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by name only — never paste token values. Do not disable live webhooks or jobs (the bundled machine-status job stays enabled: false unless the operator turns it on after a fork).

Secrets

Hosts: api.machines.dev (Machines REST, Bearer), api.fly.io (GraphQL / logs / Prometheus, Bearer / FlyV1).

Import paths

Prefer static kody:@kody/fly/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only)

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

import smokeTest from 'kody:@kody/fly/smoke-test'

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

Equivalent via root dispatcher:

import fly from 'kody:@kody/fly'

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

List apps:

import fly from 'kody:@kody/fly'

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

dryRun / confirm

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'

export default async function main() {
	const preview = await startMachine({
		appName: 'my-app',
		machineId: '148e26d9b3e089',
		dryRun: true,
	})
	return preview
}

Edge cases

• No Fly app names or organization slugs are baked in — callers supply them.
• When organizationSlug is omitted and the token sees multiple orgs, pass an explicit slug.
• Do not enable the machine-status job on the official listing; after a fork, enable only if the operator wants the periodic read.