The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 116 lines 3.87 KB
Raw
1 ---
2 title: Setup
3 description: Create a Fly org, generate an API token, and store it in a profile.
4 ---
5
6 import PackageManagers from "../../../components/PackageManagers.astro";
7
8 export const pkgs = `alchemy@latest @alchemy.run/fly@latest effect @effect/platform-bun @effect/platform-node`;
9
10 Everything you need before deploying to Fly.io: the alchemy package,
11 a Fly organization, and an API token stored in a profile.
12
13 ## Prerequisites
14
15 - [Bun](https://bun.sh) or Node.js 22+
16 - A [Fly.io](https://fly.io) account
17 - [Docker](https://docs.docker.com/get-docker/) for
18 [Services](/fly/compute/services) (Alchemy builds and pushes an
19 image). Raw [Machines](/fly/compute/machines) with a public image
20 do not need it. Neither do
21 [Sprites](/fly/compute/sprites).
22
23 ## Create a Fly organization
24
25 Sign in at [fly.io/dashboard](https://fly.io/dashboard). A personal
26 org is created with the account. Tokens are scoped to an org — the
27 org slug is where Services create their Apps, and what `Fly.App`
28 uses when you omit `orgSlug` (Alchemy reads it from the current
29 token).
30
31 ## Generate an API token
32
33 In the dashboard:
34
35 1. Open **Account** → **Access Tokens** (or run `fly tokens create org`
36 if you have [flyctl](https://fly.io/docs/flyctl/install/)).
37 2. Create an **organization** token with permission to manage Apps
38 and Machines.
39 3. Copy the token — Fly shows it **only once**.
40
41 The official environment variable is `FLY_API_TOKEN`. That token is
42 enough for Apps, Machines, Services, Sprites, Postgres, Redis, and
43 Tigris. Alchemy mints a Sprites bearer from it when you deploy a
44 Sprite.
45
46 ## Create a project directory
47
48 <PackageManagers init dir="my-app" />
49
50 ## Install
51
52 <PackageManagers add={pkgs} />
53
54 ## Connect alchemy to Fly
55
56 There is no separate credentials step. The first time you run
57 `alchemy deploy` (or `plan`, `dev`, `destroy`) on a stack that uses
58 `Fly.providers()`, alchemy prompts for the token you generated above
59 (and, optionally, a Machines API hostname — default
60 `https://api.machines.dev/v1`). It is saved under
61 `~/.alchemy/credentials/<profile>/` in your **`default`**
62 [profile](/environments/profiles) and reused on every subsequent
63 command.
64
65 In CI (`CI=true`) alchemy skips the prompt and reads `FLY_API_TOKEN`
66 (plus an optional `FLY_API_HOSTNAME`) from the environment instead.
67
68 To re-run the setup later (e.g. to rotate the token, or configure a
69 separate `prod` profile):
70
71 ```sh
72 # Re-run the interactive setup (e.g. to rotate the token)
73 alchemy profile edit --reconfigure Fly
74
75 # Or connect Fly in a separate `prod` profile
76 alchemy profile create prod
77 alchemy profile edit --profile prod --add Fly
78
79 # Non-interactive (scripts, agents)
80 alchemy profile edit --add Fly --method stored --set apiKey=env:FLY_API_TOKEN
81 ```
82
83 Inspect what's stored (secrets are redacted):
84
85 ```sh
86 alchemy profile show
87 ```
88
89 :::note[Docker is required for Services]
90 [`Fly.Service`](/fly/compute/services) bundles your Effect program,
91 builds a `linux/amd64` image, and pushes it to `registry.fly.io`.
92 Have [Docker](https://docs.docker.com/get-docker/) running on the
93 machine that runs `alchemy deploy`. Raw
94 [`Fly.Machine`](/fly/compute/machines)s that use a public image
95 (`nginx:alpine`) do not need it. Neither do
96 [`Fly.Sprite`](/fly/compute/sprites)s — Alchemy writes the bundle
97 onto the Sprite.
98 :::
99
100 ## State storage
101
102 Fly has no object-storage state backend of its own, so pick one of:
103
104 - **`Alchemy.localState()`** — state on disk under `.alchemy/` next
105 to your code. Zero setup; right for solo projects and trying
106 things out.
107 - **A cloud state store** — if you also use Cloudflare or AWS, pass
108 `Cloudflare.state()` or `AWS.state()` so state is shared with
109 your team and CI. See [State Store](/state-store).
110
111 ## Next steps
112
113 - [Tutorial part 1](/fly/tutorial/part-1) — deploy your first Service.
114 - [Sprites](/fly/compute/sprites) — an Effect program that
115 hibernates. No Docker.
116 - [Fly overview](/fly) — the map of resources and guides.