Setup

Everything you need before deploying to Fly.io: the alchemy package, a Fly organization, and an API token stored in a profile.

Prerequisites

• Bun (recommended) or Node.js 22+
• A Fly.io account
• Docker for Services (Alchemy builds and pushes an image). Raw Machines with a public image do not need it. Neither do Sprites.

Create a Fly organization

Sign in at fly.io/dashboard. A personal org is created with the account. Tokens are scoped to an org — the org slug is what Fly.App uses when you omit orgSlug (Alchemy reads it from the current token).

Generate an API token

In the dashboard:

1. Open Account → Access Tokens (or run fly tokens create org if you have flyctl).
2. Create an organization token with permission to manage Apps and Machines.
3. Copy the token — Fly shows it only once.

The official environment variable is FLY_API_TOKEN. That token is enough for Apps, Machines, Services, Sprites, Postgres, Redis, and Tigris. Alchemy mints a Sprites bearer from it when you deploy a Sprite.

Create a project directory

bun

mkdir my-app && cd my-app && bun init -y

npm

mkdir my-app && cd my-app && npm init -y

pnpm

mkdir my-app && cd my-app && pnpm init

yarn

mkdir my-app && cd my-app && yarn init -y

Install

bun

bun add "alchemy@latest" "effect@rc" "@effect/platform-bun@rc" "@effect/platform-node@rc"

npm

npm install "alchemy@latest" "effect@rc" "@effect/platform-bun@rc" "@effect/platform-node@rc"

pnpm

pnpm add "alchemy@latest" "effect@rc" "@effect/platform-bun@rc" "@effect/platform-node@rc"

yarn

yarn add "alchemy@latest" "effect@rc" "@effect/platform-bun@rc" "@effect/platform-node@rc"

Connect alchemy to Fly

There is no separate credentials step. The first time you run alchemy deploy (or plan, dev, destroy) on a stack that uses Fly.providers(), alchemy walks you through an interactive login with two options:

• API Token — paste the token you generated above. It’s verified against the Machines API and saved under ~/.alchemy/credentials/<profile>/.
• Environment Variables — reads FLY_API_TOKEN from the environment on every run (plus an optional FLY_API_HOSTNAME to override the Machines API root, default https://api.machines.dev/v1). This is the method for CI — when alchemy detects CI=true it skips the prompt and uses the environment automatically.

Either choice is saved to your default profile and reused on every subsequent command.

To re-run the setup later (e.g. to rotate the token, or configure a separate prod profile):

alchemy login --configure
alchemy login --profile prod --configure

Inspect what’s stored (secrets are redacted):

alchemy profile show

Docker is required for Services

Fly.Service bundles your Effect program, builds a linux/amd64 image, and pushes it to registry.fly.io. Have Docker running on the machine that runs alchemy deploy. Raw Fly.Machines that use a public image (nginx:alpine) do not need it. Neither do Fly.Sprites — Alchemy writes the bundle onto the Sprite.

State storage

Fly has no object-storage state backend of its own, so pick one of:

• Alchemy.localState() — state on disk under .alchemy/ next to your code. Zero setup; right for solo projects and trying things out.
• A cloud state store — if you also use Cloudflare or AWS, pass Cloudflare.state() or AWS.state() so state is shared with your team and CI. See State Store.

Next steps

• Tutorial part 1 — deploy your first App.
• Sprites — an Effect program that hibernates. No Docker.
• Fly overview — the map of resources and guides.