An introduction to Fly Machines

Illustration by Annie Ruygt of some birds launching a Fly rocket

Fly Machines are fast-launching VMs with a simple REST API. They’re the compute behind the Fly.io platform. If you’ve launched an app on Fly.io, you’re already using Fly Machines. We use the Machines API to build the orchestration for Fly Launch. You can use it however you’d like.

Do I need to control Machines directly?

We give you low-level control over Fly Machines for when you need to be picky about how, where, and when to start VMs on Fly.io. For most applications, most of the time, you don’t need to be picky! You scale things up to more cores or more memory, and out to more regions and more Machine counts. Fly Launch does all that for you with simple syntax and configuration.

Concepts

You can create and destroy Machines directly, and you have control over every Machine’s lifecycle, resources, and region placement.

Machines

A Machine is the configuration and state for a single VM running on Fly.io. Every Machine will belong to a Fly App; Apps can have more than one Machine. You can start a Machine right now, without configuring anything:

fly machine run --shell

? Select Organization: (personal)
Searching for image 'ubuntu' remotely...
Image size: 30 MB

Success! A machine has been successfully launched in app flyctl-interactive-shells-g1b7jg6wpdbq0i8b8yrl4q9rlqu5pm-502673
 Machine ID: d8d9510a295118
Connecting to fdaa:1:18:a7b:191:1aa9:a2a5:2... complete
root@d8d9510a295118:/# uname -a
Linux d8d9510a295118 5.15.98-fly #gf0950f1d7c SMP Sun Sep 17 02:33:12 UTC 2023 x86_64 x86_64 x86_64 GNU/Linux

Go ahead and try it! When you run a Machine with --shell, we’ll make a small one, and we’ll tear it down when you’re done poking around.

Machine state

The big Fly Machine trick is: starting up super fast; like, “in response to an HTTP request from a user” fast. Doing things like that is why you’d use Fly Machines directly, rather than letting flyctl run your deployment. To get your head around that trick, start by understanding the lifecycle of a Fly Machine:

You create a Fly Machine with a Create Machine request, or with fly machine run. The Machine is in created state while we reserve space for your Machine, fetch your container from our global registry, and then build a root file system; this can take some time, maybe low double digit seconds.
Once the Fly Machine exists, we boot it up for you right away. The Machine is in started state. It’s running. You can talk to it. This happens fast! Everything’s already assembled; we’re just booting. Usually this takes well under a second. The same goes for starting a stopped Machine with a Start Machine request, or with fly machine start.
You’re done with the Fly Machine, so you stop it with a Stop Machine request, or fly machine stop. The VM shuts down. The Machine is in stopped state. Its components are still assembled on our worker host, ready to start back up; if you want to do that, GOTO 2.
You’re tired of the Fly Machine, and want it to go away permanently. Send a Delete Machine request, or use fly machine destroy. We clear the resources we were holding for the Machine off our server. You can easily create and start a new Machine from the same image, but it’ll be slower than stopping and starting an existing Machine.

Learn more about running a new Machine or updating a Machine with flyctl commands.

Scaling Machines

Remember, the ordinary way to scale an application on Fly.io is to use Fly Launch, which offers convenient commands to scale instances out or up. Here, we’re going to scale Machines directly, in a fiddly way.Whether or not you use fly launch to boot up a Fly App, every Machine belongs to an “App” (an “App” is ultimately just a named collection of resources, configuration, and routing rules).

Scale a workload out horizontally with fly machine clone:

fly machine clone -a my-app --region ord 7811373c095228

Cloning machine 7811373c095228 into region ord
Provisioning a new machine with image registry-1.docker.io/my-app/sleep:latest@sha256:597c3e
  Machine 28749edf4047d8 has been created...
  Waiting for machine 28749edf4047d8 to start...
Machine has been successfully cloned!

You can clone a specific Machine as many times as you like, into specific regions; you can manage each of those Machines individually with fly machine stop and fly machine start. Scale a Machine up vertically with fly machine update:

fly machine update -a my-app --vm-memory 512M 7811373c095228

Configuration changes to be applied to machine: 7811373c095228 (twilight-field-6033)

  	... // 12 identical lines
  	    "cpu_kind": "shared",
  	    "cpus": 1,
- 	    "memory_mb": 256
+ 	    "memory_mb": 512
  	  },
  	  "dns": {}
  	}
  	
? Apply changes? Yes
Updating machine 7811373c095228
No health checks found
Machine 7811373c095228 updated successfully!

Updating a Machine takes it down (like with fly machine stop), applies configuration changes, and brings it back up. If you’re not changing the image, so we don’t have to go fetch it from the global registry, this is fast, for the same reason stop and start are; we’ve already done the heavy lifting.

Static Machine IPs

App-scoped static egress IPs are recommended. The machine-scoped static egress IPs described below are a legacy feature. For most use cases, you should allocate app-scoped static egress IPs instead. Unlike machine-scoped IPs, app-scoped IPs can be shared between multiple machines in a region and are not deleted when machines are recreated.

A machine-scoped static egress IP is attached to a single machine and isn’t shared with other machines. It survives a machine migration. Static egress IPs are useful when your machine needs to connect to a service that requires allowlisting a specific set of IPs. If supported, it is recommended to use WireGuard to connect to external services. You can attach a static egress IP to your machine with fly machine egress-ip allocate <machine_id>

fly machine egress-ip allocate e784e7d9a65208

? Looks like you're allocating a static egress (outgoing) IP. This is an advanced feature, and is not needed by most apps.
Are you sure this is what you want? Yes
Allocated egress IPs for machine e784e7d9a65208:
IPv4: 209.71.93.224
IPv6: 2a09:8280:e600::2e:951:0

Placement

When you create, run, or clone a Machine, you can pick a Fly.io region to place it in. Our API will contact the Machines API server (we call it flaps, but you don’t have to care), which will in turn reach out to all the worker servers we have in the region, find out which ones have the requisite resources to host the Machine, and try to make a smart choice about which of those servers to put the Machine in. You don’t get to pick particular servers (there are ways to cheat and do it anyways, but you shouldn’t want to), just the region. If you pick a particular region, like ord or yyz, we will only create the Machine in that region. Read more about Machine placement and regional capacity in this guide.

Placement can fail! It shouldn’t happen often, but we can run out of capacity in particular regions. Both flyctl and the Fly Machines API are best-effort. If you’re working with us at this level of control, it’s on you to retry requests and ensure they go through. In exchange for that burden, we try to make sure the Fly Machines API is responsive, so you get quick answers.

Recapping Fly Machine features

Manage with the Machines API or flyctl commands
Stop automatically when a program exits
Stop or start quickly, either manually or automatically based on traffic
Provide ephemeral storage, a blank slate on every startup
Attach a volume for persistent storage
Place in any region

Machine states and lifecycle Find out how Machines move through states (created → started → stopped etc), what it means, how to detect issues.
Machine placement and regional capacity Learn more about how region and host capacity affect where your Machines land and what to do if placement fails.
fly machine CLI reference Use this command‑line reference for managing Machines via flyctl (create, update, stop, clone, etc).
Working with the Machines API Read a practical guide to creating, updating, and managing Machines via API calls.
Machines API reference Use this low-level reference for the Machines API runtime, generated from the OpenAPI specification.

​Do I need to control Machines directly?

​Concepts

​Machines

​Machine state

​Scaling Machines

​Static Machine IPs

​Placement

​Recapping Fly Machine features

​Related reading

Do I need to control Machines directly?

Concepts

Machines

Machine state

Scaling Machines

Static Machine IPs

Placement

Recapping Fly Machine features

Related reading