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

main
mdx 253 lines 9.4 KB
Raw
1 ---
2 title: Machines
3 description: A Firecracker VM running a container image.
4 ---
5
6 A [`Fly.Machine`](/providers/fly/machine) is a Firecracker VM
7 running a container image. Use it when you already have an image.
8
9 ## Launch a Machine
10
11 A Machine runs in a [`Fly.App`](/fly/compute/apps) you declare:
12
13 ```typescript
14 // src/app.ts
15 export const Site = Fly.App("Site");
16 ```
17
18 Pin a [region](/fly/compute/regions), an image, and a guest:
19
20 ```typescript
21 const web = yield* Fly.Machine("Web", {
22 app: Site,
23 region: "iad",
24 image: "nginx:alpine",
25 guest: { cpuKind: "shared", cpus: 1, memoryMb: 256 },
26 services: [
27 {
28 protocol: "tcp",
29 internalPort: 80,
30 ports: [
31 { port: 80, handlers: ["http"], forceHttps: true },
32 { port: 443, handlers: ["tls", "http"] },
33 ],
34 },
35 ],
36 });
37 ```
38
39 `region` replaces on change. `image` updates in place by default; the
40 opt-in blue/green strategy prepares replacement Machines instead. Guest
41 defaults to shared-cpu 1× / 256 MB. Port 443 with `tls` is what
42 makes `https://{app}.fly.dev` answer. Omit `services` (or pass
43 `[]`) for a worker that should not be reachable from the internet.
44
45 The App needs an
46 [`IpAssignment`](/fly/networking#addresses-for-a-shared-app) before
47 `{app}.fly.dev` answers over IPv4. For a public endpoint without
48 managing Apps and addresses, use a [Service](/fly/compute/services).
49
50 ## Run named containers
51
52 Use `containers` for a group that shares one Machine. Each named container has its own image and can set `cmd`, `entrypoint`, `env`, startup `dependsOn`, and Pilot `healthChecks`. Use `cmd` and `entrypoint` to override startup; container `exec` overrides are not supported. Existing single-image `init.exec` is unchanged. Check intervals and timeouts are numeric seconds. A dependency condition can be `started`, `healthy`, or `exited_successfully`.
53
54 ```typescript
55 const preview = yield* Fly.Machine("Preview", {
56 app: Site,
57 region: "iad",
58 guest: { cpus: 1, memoryMb: 1024 },
59 containers: [
60 { name: "api", image: apiImage, healthChecks: [{ http: { port: 3000, path: "/health" } }] },
61 { name: "worker", image: workerImage, dependsOn: [{ name: "api", condition: "healthy" }] },
62 ],
63 });
64 ```
65
66 `count` duplicates the entire group. A rolling change to one container can restart the whole group; attached volumes stay with their Machine. Machine `env` and bindings remain shared, while container `env` is passed to Fly as a per-container override. Configure Machine or service readiness checks for every critical component before treating a deploy as ready: Pilot container checks and dependencies control startup, not Alchemy's rollout readiness. Blue/green also supports named containers when every image is an immutable
67 `repository@sha256:` digest and no volumes are attached. It replaces the
68 whole group and can overlap old and new workers during promotion.
69
70 If a rolling update is interrupted, Fly may have accepted the update even
71 though the CLI reported a failure. Wait for the in-progress Machine update to
72 settle, then rerun the same desired deployment. Reconciliation reuses the
73 owned Machine and its attached volumes.
74
75 ## Scale up
76
77 A Machine resource runs one VM by default. Set `count` to manage
78 several replicas together, or declare separate resources for Machines
79 with different configuration. Fly's proxy load-balances published
80 `services` across them.
81
82 ```typescript
83 const web1 = yield* Fly.Machine("Web1", {
84 app: Site,
85 region: "iad",
86 image: "nginx:alpine",
87 services: [
88 {
89 protocol: "tcp",
90 internalPort: 80,
91 ports: [
92 { port: 80, handlers: ["http"], forceHttps: true },
93 { port: 443, handlers: ["tls", "http"] },
94 ],
95 },
96 ],
97 });
98
99 const web2 = yield* Fly.Machine("Web2", {
100 app: Site,
101 region: "iad",
102 image: "nginx:alpine",
103 services: [
104 {
105 protocol: "tcp",
106 internalPort: 80,
107 ports: [
108 { port: 80, handlers: ["http"], forceHttps: true },
109 { port: 443, handlers: ["tls", "http"] },
110 ],
111 },
112 ],
113 });
114 ```
115
116 Both `Fly.Machine` and [`Service`](/fly/compute/services) support
117 `count`. With the default rolling strategy, replicas within one resource
118 update sequentially; separate resources do not share that ordering.
119 Blue/green prepares the desired replacement topology before old retirement.
120
121 `count` is provisioned capacity, not always-running capacity. With
122 `autostop: "stop"` or `"suspend"`, replicas may be idle. `autostart` allows
123 requests to wake them, and `minMachinesRunning` controls Fly's running floor.
124 Blue/green checks a running representative plus the required floor without
125 permanently waking all idle replicas. A replacement does not inherit suspended
126 RAM. See [idle-capacity semantics](/fly/compute/deployments#keep-idle-capacity-with-stop-or-suspend).
127
128 ## Scale down
129
130 Remove a Machine from the stack. The next deploy deletes it.
131
132 ```diff lang="typescript"
133 const web1 = yield* Fly.Machine("Web1", {
134 app: Site,
135 region: "iad",
136 image: "nginx:alpine",
137 });
138 -
139 - const web2 = yield* Fly.Machine("Web2", {
140 - app: Site,
141 - region: "iad",
142 - image: "nginx:alpine",
143 - });
144 ```
145
146 ## Env, restart, metadata
147
148 ```typescript
149 const worker = yield* Fly.Machine("Worker", {
150 app: Site,
151 region: "iad",
152 image: "my-image:tag",
153 env: { LOG_LEVEL: "info" },
154 restart: { policy: "always" },
155 });
156 ```
157
158 Alchemy stamps `alchemy.stack` / `alchemy.stage` / `alchemy.id` /
159 `alchemy.type` onto `config.metadata` so `list()` can find owned
160 Machines. Fly injects App [secrets](/fly/data/secrets) as env vars
161 on the Machine. `minSecretsVersion` requires at least that secret version;
162 it is a floor, not an immutable snapshot. Machine leases do not serialize
163 standalone `Fly.Secret`, other Services, or runtime vault writers. A later
164 writer can advance the shared App vault. Set an explicit deployment input
165 or version floor when an out-of-band rotation requires a new rollout;
166 secret changes are not automatically watched.
167
168 ## Mounts
169
170 Pass disks as `mounts`. Alchemy creates a Volume in the Machine's
171 app and region. A Volume attaches to one Machine.
172
173 ```typescript
174 const box = yield* Fly.Machine("Box", {
175 app: Site,
176 region: "iad",
177 image: "nginx:alpine",
178 mounts: [{ path: "/data", sizeGb: 1 }],
179 });
180 ```
181
182 From a Service, prefer [`MountVolume`](/fly/data/volumes) so the
183 path is part of the binding graph.
184
185 ## Lifecycle
186
187 For replicas required to run, reconcile waits until the Machine is
188 `started` (`waitMachine`, bounded). It then waits for configured readiness
189 checks. With default rolling updates, this happens before the next replica.
190 The default readiness budget is 60 seconds; set `deploy.healthTimeout`
191 for a longer bounded wait. A failed wait stops the rollout with
192 `Fly.ReplicaChecksNotPassing` and
193 the last observed check names, statuses, and output. Later replicas
194 remain unchanged; earlier updates are not automatically rolled back.
195 The default rolling strategy updates in place, so a single replica can be
196 unavailable while it updates. Set `deploy: { strategy: "bluegreen" }` to
197 [prepare checked replacement Machines before retirement](/fly/compute/deployments).
198
199 For rolling, `skipLaunch: true` creates or updates config without starting
200 or checking it. By default, delete force-destroys and waits until gone.
201 Setting `shutdown` or enabling blue/green instead cordons reachable
202 predecessors, signals each with its own persisted shutdown policy, waits
203 for it to stop, and verifies deletion. A new generation's shorter timeout
204 must not shorten the old process's grace window.
205
206 A raw image must handle signals, stop accepting work, and drain requests or jobs.
207 These props do not install the Effect runtime in it. A genuinely unreachable
208 host may require force-deleting an owned stateless predecessor once its
209 replacement is ready. This cannot prove the old work drained. See the
210 [deployment and recovery limits](/fly/compute/deployments).
211
212 Alchemy uses native Machine leases. It reports contention rather than stealing
213 a lease. These leases do not lock the whole App or serialize every first
214 deployment. Serialize CI deployments to the same resource. LocalState is not
215 a cross-process lock, and App deletion has no Machine-lease precondition.
216
217 `autoDestroy: true` removes a Machine when its process exits. Blue/green requires
218 a persistent process and rejects this option, explicit `skipLaunch`, attached
219 volumes, and missing readiness checks. It reports unsupported settings rather
220 than silently switching to rolling. Stop and suspend are supported through the
221 [idle-capacity rules](/fly/compute/deployments#keep-idle-capacity-with-stop-or-suspend).
222
223 ## Service or Sprite
224
225 Prefer a [`Service`](/fly/compute/services) when the program is
226 Effect. A Service is effectful, supports bindings, and scales with
227 `count`. It owns its App and addresses, and `api.url` is its public
228 endpoint. Alchemy builds and pushes the image. Prefer a
229 [`Sprite`](/fly/compute/sprites) when the sandbox can hibernate —
230 no App, no Docker image.
231
232 ```typescript
233 export default class Api extends Fly.Service<Api>()(
234 "Api",
235 { main: import.meta.url, region: "iad", count: 3, port: 3000 },
236 Effect.gen(function* () {
237 return {
238 fetch: Effect.succeed(HttpServerResponse.text("hello")),
239 };
240 }),
241 ) {}
242 ```
243
244 ## Where next
245
246 - [Blue/green deployments](/fly/compute/deployments) — readiness, graceful shutdown, and recovery.
247
248 - [Services](/fly/compute/services) — bundle an Effect program into
249 a Machine.
250 - [Regions](/fly/compute/regions) — where a Machine lives.
251 - [Volumes](/fly/data/volumes) — persistent disks.
252 - [`Machine` reference](/providers/fly/machine) — every prop and
253 attribute.