Skip to main content
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:
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:
  1. 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.
  2. 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.
  3. 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.
  4. 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:
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:
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>

​
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