import PackageManagers from "../../../components/PackageManagers.astro"; export const pkgs = `alchemy@latest @alchemy.run/fly@latest effect @effect/platform-bun @effect/platform-node`; 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:
- Open Account → Access Tokens (or run
fly tokens create orgif you have flyctl). - Create an organization token with permission to manage Apps and Machines.
- 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
Install
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 :::note[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()orAWS.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.