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 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 where Services create their Apps, and 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 Service.
• Sprites — an Effect program that hibernates. No Docker.
• Fly overview — the map of resources and guides.