Apps

A Fly.App is a global namespace in your account. It contains Machines, Services, Secrets, IPs, and certificates.

A Service creates and manages its own App, so you do not declare one to deploy a Service. Declare a Fly.App when you need one directly:

• Machines run in an App you declare.
• Fly.Secret, SecretKey, Fly.Certificate, and IpAssignment attach to a Fly.App, not to a Service’s own App.
• Several Services share one hostname, secrets, or domain — see Group Services in one App.

Create an App

Alchemy generates a unique name unless you pass one.

const site = yield* Fly.App("Site");

url is https://{appName}.fly.dev. Nothing answers there until a Machine or a grouped Service publishes a proxy service and the App has an IP assignment.

Note

Prefer omitting name in tests and CI so names stay unique and reclaimable.

A stable hostname

Pass name when you need a stable fly.dev hostname.

const site = yield* Fly.App("Site", {
  name: "my-site",
});

Changing name replaces the App

Fly cannot have two Apps with the same name. Alchemy deletes the old App first, then creates the new one.

Organization

Org defaults to the current token. Pass orgSlug to pin it.

const site = yield* Fly.App("Site", {
  name: "my-site",
  orgSlug: "my-org",
});

Changing orgSlug replaces the App

The App is created in the new org. The old App is deleted.

Subdomains

enableSubdomains: true turns on *.{appName}.fly.dev.

const site = yield* Fly.App("Site", {
  name: "my-site",
  orgSlug: "my-org",
  enableSubdomains: true,
});

Create-only

Flipping enableSubdomains later is ignored.

Isolated network

network is an optional 6PN name.

const site = yield* Fly.App("Site", {
  name: "my-site",
  orgSlug: "my-org",
  enableSubdomains: true,
  network: "private",
});

Changing network replaces the App

The App is recreated on the new network.

Module-scope declarations

Declare the App once. Pass it into every child.

src/app.ts

import * as Fly from "alchemy/Fly";

export const Site = Fly.App("Site");

Resource-valued props accept the resource or an Effect producing it. Do not unwrap it just to pass it along.

Destroy

alchemy destroy deletes children, then the App.

Where next

Services own their App by default and join one with app. Machines run a raw image in an App. IPs & certificates covers addresses and domains on an App. The App reference lists every prop.