@intentius/chant-lexicon-fly

The Fly.io lexicon for chant. Declare Fly apps, machines, volumes, IPs, certificates, and secrets as typed TypeScript and apply them straight to the Fly Machines API.

npm install --save-dev @intentius/chant @intentius/chant-lexicon-fly

Test it without a Fly account

Fly's Machines API is emulated by mudflaps, a stateful Fly Machines API emulator. The entire apply-and-deploy loop runs against a local mudflaps container in CI, with no Fly account and no bill. The same code then deploys to a real org by changing one endpoint, so the loop you test offline is the loop you ship.

cd examples/local-fly
chant run fly        # boots mudflaps, applies an App + Machine, waits for started, tears down

What it does

chant is a type system for operations: you describe infrastructure as typed TypeScript, and each lexicon turns those declarations into real provider API calls. This one covers Fly.

The resource types (App, Machine, Volume, IPAddress, Certificate, Secret) are generated from Fly's own Machines API OpenAPI spec, so they track the real API and give you full editor autocomplete. A build step lints them, and flyApply reconciles them against a Fly org over the Machines API (flaps) directly.

It fits two kinds of user: teams running on Fly who want their infrastructure as typed, reviewed, reconciled code rather than imperative CLI calls, and platform engineers who already manage AWS, GCP, or Kubernetes through chant and want Fly in the same model.

Author infrastructure as typed code

import { App, Machine, MachineConfig, MachineGuest, Fly } from "@intentius/chant-lexicon-fly";

export const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });

export const web = new Machine({
  region: "iad",
  config: new MachineConfig({
    image: "flyio/hellofly:latest",
    guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
  }),
});

MachineConfig is typed all the way down through guest, services, mounts, and checks, because the whole graph is generated from the Machines API spec.

Apply without a state file

flyApply speaks the Machines API directly. There is no flyctl shell-out and no state file to store, lock, or keep in sync. It reconciles what you declared against what is actually running:

• Creates and updates machines, then waits each one to started over the Machines API /wait endpoint.
• Prunes only what chant owns. Every machine chant creates carries a managed-by: chant marker, and a machine without it is never modified or deleted, so the applier is safe to point at an app that also holds resources you manage elsewhere.
• Speaks the Machines API lease protocol: acquire a lease, send the nonce on each mutation, re-acquire and retry if the lease is lost, so concurrent operators stay out of each other's way.

The endpoint is a single switch. Set FLY_FLAPS_BASE_URL (or pass an endpoint) to choose between a real Fly org and a local emulator with no code change.

Catch mistakes at build time

Lint rules run during chant build, before anything reaches the API:

• region must be a real Fly region.
• Guest sizing (cpu_kind / cpus / memory_mb) must be a valid combination.
• Every machine mount must reference a Volume declared in the stack, checked across files.
• Secret values may not be written inline; they belong in a Secret or a reference.

The deploy Op

The lexicon ships a deploy Op that runs the phases boot, build, apply, verify, and teardown, and a runnable examples/local-fly starter. As shown above, chant run fly boots mudflaps, builds the plan, applies the App and Machine, waits for the machine to reach started, and tears the emulator down. Drop the local endpoint and set FLY_API_TOKEN, and the same Op deploys to a real Fly org.

Compared to a Terraform provider for Fly

| | Terraform for Fly | This lexicon | | ------------ | ---------------------------------------- | ------------------------------------------------------- | | State | A .tfstate to store, lock, and back up | None; reconciles from live state + the ownership marker | | Language | HCL | TypeScript, types generated from the Machines API spec | | Testing | Against a real Fly org | Offline against the mudflaps emulator, in CI |

The same code applies to a local emulator and to a real Fly org; the only difference is the endpoint.

Agent skill

The agent-facing entry point is the chant-fly skill: a short operational playbook that walks an agent through authoring an App and Machine, linting with chant build, and reconciling over the Machines API with flyApply, including the FLY_FLAPS_BASE_URL switch between mudflaps and a real org. It ships with two companions, chant-fly-patterns (volumes, IPs, certificates, apply-only secrets, and the ownership model) and chant-fly-ops (waiting, leases, prune, and teardown). The skill sources live in src/skills/.

Related packages

| Package | Role | | ------------------------------------------------------------------------------------------ | ------------------------------------- | | @intentius/chant | Core type system, CLI, build pipeline | | @intentius/chant-lexicon-aws | AWS CloudFormation lexicon | | @intentius/chant-lexicon-gcp | GCP Deployment Manager lexicon |

License

See the main project LICENSE file.