Run a new Machine

Illustration by Annie Ruygt of a phoenix jumping with a motor bike

The fly machine run command is a tool to configure, build, and start a new Machine in one line. Many, but not all, Machine configuration options are available to the fly machine run command through flags. The available flags are listed in the flyctl help and on the fly machine run reference page. Use fly machine run when you want use more than one Docker image in an app, or to run a one-off or temporary Machine.

To create a Machine, but not start it, use fly machine create.To make changes to a Machine once it’s created or run, use fly machine update.To create and run a new Machine with the same configuration as an existing Machine, use fly machine clone.To add a new Machine to an app managed by fly deploy, see the scaling doc for Fly Launch apps. By default, fly machine run creates Machines that are ignored by Fly Launch features like fly deploy, fly status, and fly scale.

What it does

Here’s what fly machine run does for you:

Checks with the platform for the org and app you’ve specified, if any, and if needed, guides you through naming a new app.
Creates a Fly App, if applicable.
Gets, or builds, a Docker image to make the Machine from, and pushes it to the Fly.io registry if applicable.
Creates the Machine with some default config, plus config you pass to it with flags.
Starts the Machine.
By default, waits for the Machine to start, and for any configured health checks to pass, before declaring success (or failure).

Usage

Here’s the usage of fly machine run:

fly machine run <image> [command] [flags]

Here, <image> can point to a prebuilt image, or to the current directory (.) to build from a Dockerfile.

Administration: set the Machine’s app and org

The default behavior of fly machine run is to create a new Fly App for the new Machine to belong to, unless it’s given the name of an existing app in one of two ways:

Like many flyctl commands, fly machine run will pull an app name from a fly.toml file if one is present in the working directory. It disregards the rest of the configuration in the file.
If you pass it an app name with --app <app-name>, flyctl prefers that name over any name it gets from a fly.toml.

If the app name doesn’t belong to an existing app in one of your orgs, flyctl asks if you want to create it. It may be worth creating a fly.toml file with just the app name in it, to save using the --app option repeatedly. For example:

# a fly.toml just to provide an app name to commands
# run from the same directory

app = my-app-name

Use --org <org-name> to specify which organization a newly created app should belong to. The --org flag is ignored when creating the new Machine in an existing app.

Name the Machine

Machines have a human-friendly name property, like ancient-glitter-2128, that shows up alongside the id in the output of the fly machine list command and in the web dashboard. You can give the Machine a custom name with the --name flag:

fly machine run . --name my-special-Machine

Choose a region

Tell the Fly.io platform which region to create the Machine in with the --region flag; if for some reason it can’t start a new Machine in that region, you’ll get an error. If the --region flag is omitted, the platform chooses the region that’s fastest to reach from your location. This sets the region property of the Machine.

Get or build the Docker image

All Fly Machines are made from Docker images. Once the Machine is created, you can see this image reflected in its image_ref and config.image properties. With fly machine run, there are two options: point to a prebuilt image, or point to a Dockerfile, which flyctl will use to build an image.

Build from a Dockerfile

To build the image from a Dockerfile named Dockerfile, indicate the current working directory using the <image> argument.

fly machine run .

Use the --dockerfile option to specify a Dockerfile with a different name. For example:

fly machine run . --dockerfile Dockerfile-dev

Any source files the Dockerfile uses should be present in the working directory. Once built, the image is pushed to the Fly.io Docker registry where your organization’s remote builders can access it.

Use an existing image

For example:

fly machine run ghcr.io/livebook-dev/livebook:0.11.4

Get a shell on a temporary Machine

The following command creates a temporary Machine using the Dockerfile in the working directory, and logs you into an interactive shell on it:

fly machine run . --shell

If you don’t specify an app, flyctl creates or reuses an app for interactive shells. When you log out of the shell, the Machine is deleted; the app is retained for future shells. The default shell is Bash. The --command flag allows you to specify a different shell if Bash isn’t present in the Machine’s Docker image. Log in as a non-root user using the --user flag. If you just want a shell on a temporary Ubuntu Machine that’s in your org’s private network, omit the <image> argument:

fly machine run --shell

Run with a custom ENTRYPOINT or CMD

You can have the Fly.io init override the ENTRYPOINT and CMD (if any) of the Machine’s Docker image.

Custom CMD

Override CMD by including the command to run at the end of the fly machine run invocation. This sets the config.init.cmd property on the Machine. This example simply spins up a Debian Linux Machine with a sleep task to keep it awake; you can shell into it or whatever:

fly machine run debian sleep inf

Custom ENTRYPOINT

Override ENTRYPOINT with the --entrypoint option. This sets the config.init.entrypoint property on the Machine. In this example we use the --file-local option to send an entrypoint script to the Machine and --entrypoint to run the script before continuing to the custom CMD sleep inf:

fly machine run debian --file-local /entrypoint.sh=./entrypoint.sh \
                       --entrypoint "/entrypoint.sh" \
                       sleep inf

Here’s a trivial entrypoint.sh you can use to test the above example:

#! /bin/bash

echo "Hello from my Fly Machine"

exec "$@"

The line “Hello from my Fly Machine” should appear in the app’s logs.

Set Machine resources

Include one or more of the following options to use non-default specifications for the Machine to be run:

--vm-cpu-kind string          The kind of CPU to use ('shared' or 'performance')
--vm-cpus int                 Number of vCPUs
--vm-gpu-kind string          If set, the GPU model to attach (a100-pcie-40gb, a100-sxm4-80gb)
--vm-memory string            Memory (in megabytes) to attribute to the VM
--vm-size string              The VM size to set machines to. See "fly platform vm-sizes" for valid values

These flags set config.guest properties.

Set environment variables

Specify environment variables to be available on the Machine with the --env flag, using NAME=VALUE pairs. This flag sets the config.env property on the Machine. Example:

fly machine run . --env MY_VAR=MY_VALUE \
                  --env MY_OTHER_VAR="my spacey value" \
                  --app my-app-name

Use quotes around the value if it has spaces in it. For sensitive environment variables, set secrets on the app instead.

Define a Fly Proxy network service

The --port option defines a network service to allow the Fly Proxy to reach a local service on the Machine. This option gives you access to basic service configuration; the Machines API and Fly Launch both offer more control over the Machine’s config.services properties. Map any external ports, where the proxy accepts requests directed at the app, to the internal port where the service is listening on IPv4. For each port combination, specify the protocol and connection handler(s), using this format:

port[:machinePort][/protocol[:handler[:handler...]]]

For example, if your Machine runs a server on port 80, and the Fly Proxy should handle HTTP connections on port 80 and HTTPS connections on port 443, the port configuration would look like this:

fly machine run . --port 80/tcp:http \
                  --port 443:80/tcp:http:tls \
                  --app my-app-name

Important: If Machines within the same Fly App host different services, use different external ports so that they don’t receive requests meant for another Machine.

Set Fly Proxy autostop/autostart

The --autostart and --autostop flags only work on Machines with Fly Proxy services configured. Learn more about how Fly Proxy autostop/autostart works and how to configure it. In a Machine service’s configuration, autostop and autostart settings are optional. If the --autostop flag is absent in a fly machine run command, the Machine’s config.services.autostop value doesn’t get set, and the Fly Proxy does not shut the Machine down, even when there is no traffic to it. If the --autostart flag is absent in a fly machine run command, the Machine’s config.services.autostart value doesn’t get set, and the Fly Proxy does not start it in response to requests. The --autostart and --autostop flags set the value of autostart or autostop to true by default; you can explicitly set the value to false. For example, the following runs a new Machine that may be stopped by the Fly Proxy, but will never be restarted by it:

fly machine run nginx --port 80:80/tcp:http \
                --port 443:80/tcp:http:tls \
                --autostop \
                --autostart=false

If you define more than one service on the Machine, and also use one or both of these flags, the setting applies to all the services.

Stop or restart the machine on process exit

Set the Machine’s restart policy using the --restart option. Options are no, always, and on-fail, which correspond to no, always, and on-failure values for the Machine config.restart.policy property. The default restart policy for a Machine created using fly machine run is always, unless you use the --rm option, in which case the default is no.

Destroy the Machine when it exits

By default, when a Machine is stopped, its file system is reset using its config and Docker image, and it sits ready to be started again. Use the --rm flag to cause the Machine to instead be destroyed when it stops. The default restart policy for a Machine created with fly machine run --rm is no, to ensure that flyd doesn’t ignore the exit code and restart the Machine.

Mount a Fly Volume

A Fly Volume is a slice of an NVMe drive attached to the hardware that runs the Machine. Create a volume before creating the Machine.

fly volume create --size 10 data_volume --region arn

Create the new Machine in the same region, using the volume name: --volume <vol_name>:<mount_point>.

fly machine run . --volume data_volume:data --region arn

Or by id: --volume <vol_id>:<mount_point>.

fly machine run . --volume vol_d42652p88kdw9l7r:data --region arn

A Machine can only mount one volume, and each volume can only be mounted on one Machine. To release a volume that is attached to a Machine, destroy the Machine. The --volume flag on the fly machine run command sets a subset of the properties of the Machine’s config.mounts object.

Add metadata to the Machine

The Fly.io platform uses specific metadata, stored in a Machine’s config, for its own purposes, such as assigning Machines to process groups. You can add custom metadata as well. The following starts a Machine that the fly deploy command will try to manage as part of the app process group, replacing its image and config with what, if anything, you have set up in the working directory for that app.

fly machine run . --metadata fly_platform_version=v2 \
                  --metadata fly_process_group=app \
                  --metadata my_metadata=mineallmine

You can see the metadata in the Machine config:

fly machine status -d -a my-app-name

...
  "metadata": {
    "fly_platform_version": "v2",
    "fly_process_group": "app",
    "mymeta": "mineallmine"
  },
...

Place data into files on the Machine

The files property of a Machine’s configuration can be used to place data or secrets into files on the Machine file system.

Important: This won’t work for large files. There’s a limit to how much data can be stored in an app secret or a Machine’s configuration.

Copy a local file into the Machine file system

Use the --file-local flag to copy a local file onto the Machine at your specified path:

fly machine run . --file-local /path/inside/machine=local/path

flyctl Base64-encodes the file contents and stores the result in the files.raw_value property of the Machine’s config; /path/inside/machine is stored in files.guest_path. When the Machine is created, the data is decoded and written to the file.

Pass data in on the command line

Place data into a file at your specified path, via an argument of the --file-literal flag:

fly machine run . --file-literal /path/inside/machine="Some text I want in a file"

In a shell session on the Machine:

root@2865553aedd268:/# cat /path/inside/machine
Some text I want in a file

If your data isn’t a simple string like in the above example, you can Base64-encode it first, and have your app code decode the contents of the file into the original format:

fly machine run . --file-literal /b64file=SGVsbG8hIEknbSBGcmFua2llIHRoZSBiYWxsb29uIQo=

In a shell session on the Machine:

root@1857779a44d108:/# cat b64file | base64 --decode
Hello! I'm Frankie the balloon!

flyctl Base64-encodes the data and stores the result in the files.raw_value property of the Machine’s config; /path/inside/machine is stored in files.guest_path. When the Machine is created, the data is decoded and written to the file.

Make a secret available in a file

Fly Secrets are stored in an encrypted vault, and by default they are available as environment variables on each of the app’s Machines. You can make a secret available in a file, rather than an environment variable. Encode the data in Base64 format and put it into an app secret with fly secrets set or fly secrets import. Use the --stage flag to prevent flyctl from initiating a deployment once the secret is registered.

Important: The secret must be Base64-encoded. If you try this with a secret that is not Base64-encoded, Machine creation fails.

Example with a simple secret:

fly secrets set \
  MY_BASE64_SECRET=SGVsbG8hIEknbSBGcmFua2llIHRoZSBiYWxsb29uIQo= \
  --stage

Use the --file-secret flag when creating the Machine with fly machine run. In this example I’m putting the contents of the secret called MY_BASE64_SECRET into a file /secret-file on my new Machine:

fly machine run . \
  --file-secret /secret-file=MY_BASE64_SECRET

The secret is available in the specified file, and not in an environment variable, on that Machine. It’s decoded from Base64 into plain text.

root@1857770b4e10e8:/# cat secret-file
Hello! I'm Frankie the balloon!

It can be useful to store multiple key-value pairs in a single secret. The following command Base64-encodes the contents of the text file local-secrets and registers the Base64-encoded string as the value of the secret MY_SECRETS on the app:

fly secrets set MY_SECRETS="$(base64 < local-secrets)" --stage

Run a new Machine with the MY_SECRETS secret available in a file (/secret-file):

fly machine run ubuntu sleep inf --file-secret /secret-file=MY_SECRETS

Check it in a shell session:

root@d891116b465018:/# cat secret-file
USER="my_name"
PASSWORD="1a2s3d4f"
MACARON="macaroon in French"

If a particular process or user on the Machine should not have access to the secret, you can use an entrypoint script to change permissions on the secret file.

Warning: This is not a way to hide secret values from members of an app’s organization who have deployment privileges. Access via fly ssh commands is root access. All secrets that are set on an app are available, as either env vars or a file, in any Machine that gets updated after the secret is set.

In the case of secrets, the data itself is not stored in the Machine config; instead, the name of the secret is stored in the files.secret_name config property and when the Machine is created, that secret is retrieved from the vault and its decoded value is written to the file.

Create a standby Machine

For the sake of resilience, you can create a stopped standby for Machines that don’t have Fly Proxy services and therefore can’t be supplemented by Fly Proxy “autostart” in case of a host failure.

fly machine run . --standby-for 287444ec026748,148ed726c54768

Standby Machines normally remain stopped unless the watched Machines are affected by a host failure. To allow a standby Machine to be started, you can clear its standby configuration with fly machine update. The --standby-for flag sets the config.standbys Machine property.

Start a Machine on a schedule

Use the --schedule flag to set the Machine’s config.schedule property, which starts the Machine on a fuzzy hourly, daily, weekly, or monthly cycle. This is useful for running Machines that do a finite job, then exit. The Machine is started the first time when you run fly machine run, and again once per (approximate) hour, day, week, or month. For machines created with fly machine create --schedule, the first run will need to be manually started, since the cycle begins on the first machine start. Scheduled machines cannot be started via flyctl or Machines API commands, they will only run according to the schedule.

Important: If the host on which a stopped Machine resides doesn’t have the resources to start it when its scheduled time comes, you’ll get an error back. It’s up to you to build the appropriate level of redundancy into your apps.

​What it does

​Usage

​Administration: set the Machine’s app and org

​Name the Machine

​Choose a region

​Get or build the Docker image

​Build from a Dockerfile

​Use an existing image

​Get a shell on a temporary Machine

​Run with a custom ENTRYPOINT or CMD

​Custom CMD

​Custom ENTRYPOINT

​Set Machine resources

​Set environment variables

​Define a Fly Proxy network service

​Set Fly Proxy autostop/autostart

​Stop or restart the machine on process exit

​Destroy the Machine when it exits

​Mount a Fly Volume

​Add metadata to the Machine

​Place data into files on the Machine

​Copy a local file into the Machine file system

​Pass data in on the command line

​Make a secret available in a file

​Create a standby Machine

​Start a Machine on a schedule

What it does

Usage

Administration: set the Machine’s app and org

Name the Machine

Choose a region

Get or build the Docker image

Build from a Dockerfile

Use an existing image

Get a shell on a temporary Machine

Run with a custom ENTRYPOINT or CMD

Custom CMD

Custom ENTRYPOINT

Set Machine resources

Set environment variables

Define a Fly Proxy network service

Set Fly Proxy autostop/autostart

Stop or restart the machine on process exit

Destroy the Machine when it exits

Mount a Fly Volume

Add metadata to the Machine

Place data into files on the Machine

Copy a local file into the Machine file system

Pass data in on the command line

Make a secret available in a file

Create a standby Machine

Start a Machine on a schedule