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 prompts for the token you generated above (and, optionally, a Machines API hostname — default https://api.machines.dev/v1). It is saved under ~/.alchemy/credentials/<profile>/ in your default profile and reused on every subsequent command.

In CI (CI=true) alchemy skips the prompt and reads FLY_API_TOKEN (plus an optional FLY_API_HOSTNAME) from the environment instead.

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

# Re-run the interactive setup (e.g. to rotate the token)
alchemy profile edit --reconfigure Fly

# Or connect Fly in a separate `prod` profile
alchemy profile create prod
alchemy profile edit --profile prod --add Fly

# Non-interactive (scripts, agents)
alchemy profile edit --add Fly --method stored --set apiKey=env:FLY_API_TOKEN

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.