Working with the Machines API

This document covers usage of the Machines REST API to start, stop, update and interact with Fly Machines. For the impatient, flyctl also provides commands for experimenting with the API.

See all possible Machine states in the table below.

API spec

We have a Swagger 2.0 specification available at docs.machines.dev for the Machines API, so that you can autogenerate clients in your preferred language.

Connecting to the API

This guide assumes that you have flyctl and curl installed, and have authenticated to Fly.io.

Using the public api.machines.dev endpoint

The easiest (and recommended) way to connect to the Machines API is to use the public api.machines.dev endpoint, a simpler and more performant alternative to connecting over WireGuard.

Simply skip down to setting up the environment, and make sure to set $FLY_API_HOSTNAME to https://api.machines.dev.

Using the private Machines API endpoint

You can still access your Machines directly over a WireGuard VPN, and use the private Machines API endpoint: http://_api.internal:4280. This method requires more setup.

Follow the instructions to set up a permanent WireGuard connection to your Fly.io IPv6 private network. Once you’re connected, Fly internal DNS should expose the Machines API endpoint at: http://_api.internal:4280

Connecting through flyctl

You can also proxy a local port to the internal API endpoint. This section is preserved mainly for the sake of interest, as the public Machines API endpoint is simpler and more performant.

fly machines api-proxy

Pick any organization when asked.

With the above command running, in a separate terminal, try this to confirm you can access the API:

curl http://127.0.0.1:4280

If you successfully reach the API, it should respond with a 404 page not found error. That’s because this was not a defined endpoint.

Setting up the environment

Set these environment variables to make the following commands easier to use.

$ export FLY_API_HOSTNAME="https://api.machines.dev" # set to http://_api.internal:4280 when using Wireguard or `http://127.0.0.1:4280` when using 'flyctl proxy'
$ export FLY_API_TOKEN=$(fly auth token)

For local development, you can see the token used by flyctl with fly auth token. You can also create a new auth token in the personal access token section of the fly.io dashboard.

In order to access this API on a Fly Machine, make the token available as a secret:

fly secrets set FLY_API_TOKEN=$(fly auth token)

A convenient way to set the FLY_API_HOSTNAME is to add it to your Dockerfile:

ENV FLY_API_HOSTNAME="https://api.machines.dev"

Authentication

All requests must include the Fly API Token in the HTTP Headers as follows:

Authorization: Bearer <fly_api_token>

Apps

You can use the Apps resource to create and manage Fly Apps. A Fly App is an abstraction for a group of Machines running your code, along with the configuration, provisioned resources, and data we need to keep track of to run and route to your Machines.

Create a Fly App

POST /apps

Machines must be associated with a Fly App. App names must be unique.

curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps" \\
  -d '{
      "app_name": "my-app-name",
      "org_slug": "personal"
    }'

Status: 201

To segment the app into its own network, you can pass a network argument in the JSON body, e.g. "network": "some-arbitrary-name". Any Machine started in such an app will not be able to access other apps within their organization over the private network. However, Machines within such an app can communicate to each other, and the fly-replay header can still be used to route requests to Machines within a segmented app.

Allocate an IP address for global request routing

If you intend for Machines to be accessible to the internet, you’ll need to allocate an IP address to the app. Currently this is done using flyctl or the Fly.io GraphQL API. This offers your app automatic, global routing via Anycast. Read more about this in the Networking section.

Example:

fly ips allocate-v4 -a my-app-name

TYPE ADDRESS    REGION CREATED AT
v4   37.16.9.52 global 7s ago

The app will answer on this IP address, and after a small delay, at my-app-name.fly.dev.

Get application details

GET /apps/{app_name}

Get details about an application, like its organization slug and name. Also, to check if the app exists!

curl -i -X GET \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name" 

Status: 200

{
  "name": "my-app-name",
  "organization": {
    "name": "My Org",
    "slug": "personal"
  }
}

Set application secrets

For sensitive environment variables, such as credentials, you can set secrets as you would for standard Fly Apps using flyctl:

fly secrets set DATABASE_URL=postgres://example.com/mydb -a my-app-name

Machines inherit secrets from the app. Existing Machines must be updated to pick up secrets set after the Machine was created.

For non-sensitive information, you can set different environment variables per Machine at creation time.

Delete a Fly App

DELETE /apps/{app_name}

Machines should be stopped before attempting deletion. Append ?force=true to the URI to stop and delete immediately.

curl -i -X DELETE \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name" 

Status: 404

{
  "error": "Could not find App \"my-app-name\""
}

Machines

A Fly Machine is the configuration and state for a single VM running on Fly.io. With the Machines resource, you can create, stop, start, update, and delete Machines.

Machine properties

List all Machines for an app

GET /apps/{app_name}/machines

Query parameters for list Machines

Append parameters to filter the response.

state: Filter by the state of the Machines in the app. For example, to return only Machines in the started state: GET /apps/my-app-name/machines?started

include_deleted: If true, include deleted Machines in the response.

region: Filter by region. For example, to return only Machines in the yyz region: GET /v1/apps/my-app-name/machines?region=yyz

Example list Machines request

curl -i -X GET \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines" 

Example list Machines response

Status: 200 OK

[
  {
    "id": "a5c5de9ce64ca12",
    "name": "aged-wind-2649",
    "state": "started",
    "region": "ord",
    "image_ref": {
      "registry": "registry-1.docker.io",
      "repository": "rebelthor/sleep",
      "tag": "latest",
      "digest": "sha256:597c3e12f830132be2aa69b4c0deccb0657ea4253e6d59c6f38e41e9f69a0add"
    },
    "instance_id": "1RREBN3T5K95DK9IVP4XHTTPEY2",
    "private_ip": "fdaa:0:18:a7b:196:e274:9ce1:2",
    "created_at": "2023-10-31T02:30:10Z",
    "updated_at": "2023-10-31T02:35:26Z",
    "config": { /* Fly Machine Config */ },
    "events": [
      {
        "type": "start",
        "status": "started",
        "source": "flyd",
        "timestamp": 1698719726615
      },
      {
        "type": "launch",
        "status": "created",
        "source": "user",
        "timestamp": 1698719723203
      }
    ]
  },
  {
    "id": "9c487adb2596113",
    "name": "summer-sun-916",
    "state": "started",
    "region": "ord",
    "image_ref": {
      "registry": "registry.fly.io",
      "repository": "teamcoco",
      "digest": "sha256:5615ef423504d56ae345ccff9db54796d589965da953297f5785042df0628452"
    },
    "instance_id": "CS69NJ993EYP6VHYFXVJ9H0OBJS",
    "private_ip": "fdaa:0:18:a7b:8ba9:8eb:6d2c:2",
    "created_at": "2023-10-12T21:22:58Z",
    "updated_at": "2023-10-12T21:23:16Z",
    "config": { /* Fly Machine Config */ },
    "events": [
      {
        "type": "start",
        "status": "started",
        "source": "flyd",
        "timestamp": 1697145796337
      },
      {
        "type": "launch",
        "status": "created",
        "source": "user",
        "timestamp": 1697145792765
      }
    ],
    "checks": [
      {
        "name": "servicecheck-00-tcp-8080",
        "status": "passing",
        "output": "Success",
        "updated_at": "2023-10-12T21:23:26.014Z"
      }
    ]
  },

Create a Machine

POST /apps/{app_name}/machines

Given the name of a Fly App, create a Fly Machine, given the URI of a container image, in some region (or, by default, the region closest to you) on Fly.io’s platform. If successful, that Machine will boot up by default. Create a Machine without booting it by setting skip_launch.

You can configure the Machine characteristics, like its CPU and memory. You can also allow connections from the internet through the Fly Proxy by creating a Machine with services. Learn more about this behavior in the networking section.

The only required parameter is image in the config object.

Example create Machine request

curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines" \\
  -d '{
        "config": {
            "init": {
            "exec": [
                "/bin/sleep",
                "inf"
            ]
            },
            "image": "registry-1.docker.io/library/ubuntu:latest",
            "auto_destroy": true,
            "restart": {
            "policy": "always"
            },
            "guest": {
            "cpu_kind": "shared",
            "cpus": 1,
            "memory_mb": 256
            }
        }
      }

Example create Machine response

Status: 200 OK

{
  "id": "1857156b526dd8",
  "name": "aged-thunder-7371",
  "state": "created",
  "region": "ord",
  "image_ref": {
    "registry": "registry-1.docker.io",
    "repository": "library/ubuntu",
    "tag": "latest",
    "digest": "sha256:c9cf959fd83770dfdefd8fb42cfef0761432af36a764c077aed54bbc5bb25368",
    "labels": {
      "org.opencontainers.image.ref.name": "ubuntu",
      "org.opencontainers.image.version": "22.04"
    }
  },
  "instance_id": "01HEPA330HZ37A78TK080NAK1M",
  "private_ip": "fdaa:ff:ff:a7b:195:e229:8038:2",
  "created_at": "2023-11-08T01:52:30Z",
  "updated_at": "2023-11-08T01:52:30Z",
  "config": {
    "init": {
      "exec": [
        "/bin/sleep",
        "inf"
      ]
    },
    "image": "registry-1.docker.io/library/ubuntu:latest",
    "auto_destroy": true,
    "restart": {
      "policy": "always"
    },
    "guest": {
      "cpu_kind": "shared",
      "cpus": 1,
      "memory_mb": 256
    },
    "dns": {}
  },
  "events": [
    {
      "type": "launch",
      "status": "created",
      "source": "user",
      "timestamp": 1699408350300
    }
  ]
}

Create Machine request body parameters

name: Unique name for this Machine. If omitted, one is generated for you. String.

region: The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you). String.

lease_ttl: Acquire a lease on the newly created Machine, waiting this many seconds before failing the request; use to create a Machine that can’t be updated by any other external process while waiting for it to come up and pass health checks. Integer.

skip_launch: Create a Fly Machine, but don’t boot it up, leaving it in a state where it can be quickly started in response to events. Think of this as “warming the caches” on our hardware. Boolean (default: false)

lsvd: Enable Log Structured Virtual Disks for this Machine. Boolean (default: false)

skip_service_registration: Leave this Machine disconnected from Fly.io’s request routing. This is like a combined Create and Cordon operation; register the Machine later with an Uncordon request. Useful for bluegreen deploys: bring a Machine up, test it healthy, and only then let user requests hit it. Boolean (default: false)

config: An object defining the Machine configuration. See the config object properties section.

Create a Machine with services

POST /apps/{app_name}/machines

Create a Machine with services defined on app my-app-name. Learn more about services and networking.

Example create Machine with services request

curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines" \\
  -d '{
      "name": "quirky-machine",
      "config": {
        "image": "flyio/fastify-functions",
        "env": {
          "APP_ENV": "production"
        },
        "services": [
          {
            "ports": [
              {
                "port": 443,
                "handlers": [
                  "tls",
                  "http"
                ]
              },
              {
                "port": 80,
                "handlers": [
                  "http"
                ]
              }
            ],
            "protocol": "tcp",
            "internal_port": 8080
          }
        ],
        "checks": {
            "httpget": {
                "type": "http",
                "port": 8080,
                "method": "GET",
                "path": "/",
                "interval": "15s",
                "timeout": "10s"
            }
        }
      }
    }'

Example create Machine with services response

Status: 200 OK

{
  "id": "73d8d46dbee589",
  "name": "quirky-machine",
  "state": "starting",
  "region": "cdg",
  "instance_id": "01G3SHPT434MNW8TS4ENX11RQY",
  "private_ip": "fdaa:0:3ec2:a7b:5adc:6068:5b85:2",
  "config": {
    "env": {
      "APP_ENV": "production"
    },
    "init": {
      "exec": null,
      "entrypoint": null,
      "cmd": null,
      "tty": false
    },
    "image": "flyio/fastify-functions",
    "metadata": null,
    "restart": {
      "policy": ""
    },
    "services": [
      {
        "internal_port": 8080,
        "ports": [
          {
            "handlers": [
              "tls",
              "http"
            ],
            "port": 443
          },
          {
            "handlers": [
              "http"
            ],
            "port": 80
          }
        ],
        "protocol": "tcp"
      }
    ],
    "guest": {
      "cpu_kind": "shared",
      "cpus": 1,
      "memory_mb": 256
    },
    "checks": {
      "httpget": {
        "type": "http",
        "port": 8080,
        "interval": "15s",
        "timeout": "10s",
        "method": "GET",
        "path": "/"
      }
  },
  "image_ref": {
    "registry": "registry-1.docker.io",
    "repository": "flyio/fastify-functions",
    "tag": "latest",
    "digest": "sha256:e15c11a07e1abbc50e252ac392a908140b199190ab08963b3b5dffc2e813d1e8",
    "labels": {
    }
  },
  "created_at": "2022-05-23T22:48:21Z"
}

Wait for a Machine to reach a specified state

GET /apps/{app_name}/machines/{machine_id}/wait

Wait for a Machine to reach a specific state. Specify the desired state with the state parameter. See the Machines states table for a list of possible states. The default for this parameter is started.

This request will block for up to 60 seconds. Set a shorter timeout with the timeout parameter.

Query parameters for wait for Machine

Append parameters to filter the response.

instance_id: Filter by Machine instance_id.

timeout: Set the wait timeout. Default is 60 seconds.

state: Filter by the state of the Machines in the app.

curl -i -X GET \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/73d8d46dbee589/wait?instance_id=01GXPEEEOF95AYV5J1HYLGZ8P1&state=stopped"

Status: 200

{
  "ok": true
}

Get a Machine

GET /apps/{app_name}/machines/{machine_id}

Given the name of a Fly App and a Fly Machine ID, retrieve the details of that Machine.

Example get Machine request

curl -i -X GET \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/73d8d46dbee589" 

Example get Machine response

Status: 200 OK

{
    "id": "a5c5de9ce64ca12",
    "name": "aged-wind-2649",
    "state": "started",
    "region": "ord",
    "image_ref": {
      "registry": "registry-1.docker.io",
      "repository": "rebelthor/sleep",
      "tag": "latest",
      "digest": "sha256:597c3e12f830132be2aa69b4c0deccb0657ea4253e6d59c6f38e41e9f69a0add"
    },
    "instance_id": "1RREBN3T5K95DK9IVP4XHTTPEY2",
    "private_ip": "fdaa:0:18:a7b:196:e274:9ce1:2",
    "created_at": "2023-10-31T02:30:10Z",
    "updated_at": "2023-10-31T02:35:26Z",
    "config": { /* Fly Machine Config */ },
    "events": [
      {
        "type": "start",
        "status": "started",
        "source": "flyd",
        "timestamp": 1698719726615
      },
      {
        "type": "launch",
        "status": "created",
        "source": "user",
        "timestamp": 1698719723203
      }
    ]
}

Update a Machine

POST /apps/{app_name}/machines/{machine_id}

Given the name of a Fly App and a Fly Machine ID, update the configuration of the Machine. If the Machine is running and the request is successful, it will reboot; if the Machine isn’t running, and you don’t want it to start up, set skip_launch.

This is, in particular, how you would update the running image of a Machine (when you need to deploy new code), or roll back to a previous Machine release. It’s also how you’d vertically scale an application.

region and name are immutable and cannot be updated.

Machine update request headers

fly-machine-lease-nonce: string (nil) - The Machine lease nonce, a random value we provide that indicates that you currently hold the lease on this Machine. If the Machine is leased, and you don’t provide this header, the request to update the Machine will fail.

Example Machine update request

curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/73d8d46dbee589" \\
  -d '{
      "config": {
        "image": "flyio/fastify-functions",
        "guest": {
          "memory_mb": 512,
          "cpus": 2,
          "cpu_kind": "shared"
        },
        "env": {
          "APP_ENV": "production"
        },
        "services": [
          {
            "ports": [
              {
                "port": 443,
                "handlers": [
                  "tls",
                  "http"
                ]
              },
              {
                "port": 80,
                "handlers": [
                  "http"
                ]
              }
            ],
            "protocol": "tcp",
            "internal_port": 8080
          }
        ]
      }
    }'

Status: 200

Example Machine update response

{
  "id": "73d8d46dbee589",
  "name": "quirky-machine",
  "state": "starting",
  "region": "cdg",
  "instance_id": "01G3SHPYE8XZ58GD4XRRF9CCKC",
  "private_ip": "fdaa:0:3ec2:a7b:5adc:6068:5b85:2",
  "config": {
    "env": null,
    "init": {
      "exec": null,
      "entrypoint": null,
      "cmd": null,
      "tty": false
    },
    "image": "flyio/fastify-functions",
    "metadata": null,
    "restart": {
      "policy": ""
    },
    "guest": {
      "cpu_kind": "",
      "cpus": 2,
      "memory_mb": 512
    }
  },
  "image_ref": {
    "registry": "registry-1.docker.io",
    "repository": "flyio/fastify-functions",
    "tag": "latest",
    "digest": "sha256:e15c11a07e1abbc50e252ac392a908140b199190ab08963b3b5dffc2e813d1e8",
    "labels": {
    }
  },
  "created_at": "2022-05-23T22:48:21Z"
}

Machine update request body parameters

current_version: The latest instance_id value of the Machine.

For the rest of the parameters, see the create Machine request body parameters.

Stop a Machine

POST /apps/{app_name}/machines/{machine_id}/stop

Stopping a Machine will shut down the Machine, but not destroy it. The Machine may be started again with machines/<id>/start.

curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/73d8d46dbee589/stop" 

Status: 200

{
  "ok": true
}

Start a Machine

POST /apps/{app_name}/machines/{machine_id}/start

Start a previously stopped Machine. Machines that are restarted are completely reset to their original state so that they start clean on the next run.

curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/73d8d46dbee589/start" 

Status: 200

{
  "previous_state": "stopped"
}

Delete a Machine permanently

DELETE /apps/{app_name}/machines/{machine_id}

Delete a Machine. This action cannot be undone.

Given the name of a Fly App and the Machine ID of a Fly Machine, delete the Machine.

Example Machine delete request

Optionally append ?force=true to the URI to stop a running Machine before deleting it.

curl -i -X DELETE \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/24d896dec64879" 

Example Machine delete response

Status: 200 OK

{
  "ok": true
}

Lease a Machine

GET /apps/{app_name}/machines/{machine_id}/lease

POST /apps/{app_name}/machines/{machine_id}/lease

DELETE /apps/{app_name}/machines/{machine_id}/lease

Machine leases can be used to obtain an exclusive lock on modifying a Machine.

Example lease Machine request

curl -i -X POST \
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/3d8d413b29d089/lease" \
    -d '{
        "ttl": 500
    }'

Example lease Machine response

Status: 201 Created

{
  "status":"success",
  "data": {
    "nonce":"fed368b018e9",
    "expires_at":1666295946,
    "owner":"hello@fly.io"
  }
}

Status: 409 Conflict

{
  "status":"error",
  "message":"machine ID 3d8d413b29d089 lease currently held by hello@fly.io, expires at 2022-10-20 19:59:06 +0000 UTC",
  "code":"invalid"
}

Lease Machine request body parameters

ttl: int (nil) - How long the lease should be held for. Optional.

How to use the provided nonce

Add the fly-machine-lease-nonce header to all subsequent API calls.

For example:

curl -i -X POST \
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" -H "fly-machine-lease-nonce: fed368b018e9" \
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/3d8d413b29d089/stop"

Release the lease

For example:

curl -i -X DELETE \
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" -H "fly-machine-lease-nonce: fed368b018e9" \
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines/3d8d413b29d089/lease" 

Route requests away from a Machine

POST /apps/{app_name}/machines/{machine_id}/cordon

Given the name of a Fly App and the Machine ID of a Fly Machine, instruct the Fly Proxy not to send requests to the Machine.

You can also do this with a fresh Machine, all in one shot, using the skip_service_registration request field of a Machine Create request.

This is useful for bluegreen deployments: boot up a new, “green”, cordoned Machine running the new release (using skip_service_registration), make sure it’s healthy, then uncordon it and tear down the old, “blue” Machine.

Returns Status: 200 OK on success.

Resume request routing to a Machine

POST /apps/{app_name}/machines/{machine_id}/uncordon

Given the name of a Fly App and the Machine ID of a Fly Machine, instruct the Fly Proxy to again send requests to the Machine.

This is useful for bluegreen deployments: boot up a new, “green”, cordoned Machine running the new release, make sure it’s healthy, then uncordon it and tear down the old, “blue” Machine. This is also how you register services for a Fly Machine created with the skip_service_registration request field.

Returns Status: 200 OK on success.

The Machine config object properties

Properties of the config object for Machine configuration. Learn about all the Machine properties.

image: string - Required. The container registry path to the image that defines this Machine (for example, ”registry-1.docker.io/library/ubuntu:latest”).

auto_destroy: bool (false) - If true, the Machine destroys itself once it’s complete.

checks: An optional object that defines one or more named checks. The key for each check is the check name. The value for each check supports:

• type: string (nil) - tcp or http.
• port: int (nil) - The TCP port to connect to, likely should be the same as internal_port.
• interval: int (nil) - The interval, in nanoseconds, between connectivity checks
• timeout: int (nil) - The maximum time, in nanoseconds, a connection can take before being reported as failing its health check.
• grace_period: int (nil) - How long to wait, in nanoseconds, before we start running health checks.
• method: string (nil) - For http checks, the HTTP method to use to when making the request.
• path: string (nil) - For http checks, the path to send the request to.
• protocol: string (nil) - For http checks, whether to use http or https
• tls_server_name: string (nil) - If the protocol is https, the hostname to use for TLS certificate validation
• tls_skip_verify: bool (false) - For http checks with https protocol, whether or not to verify the TLS certificate
• headers: {string: [string, string]} ({}) - For http checks, an array of objects with string field name and array of strings field values.

An example of two checks:

        "checks": {
            "tcp-alive": {
                "type": "tcp",
                "port": 8080,
                "interval": "15s",
                "timeout": "10s"
            },
            "http-get": {
                "type": "http",
                "port": 8080,
                "protocol": "http"
                "method": "GET",
                "path": "/",
                "interval": "15s",
                "timeout": "10s"
            }
        }

dns

• skip_registration: If true, do not register the Machine’s 6PN IP with the internal DNS system.

env: {string:string} ({}) - An object filled with key/value pairs to be set as environment variables.

files: An optional array of objects defining files to be written within a Machine, one of raw_value or secret_name must be provided.

• guest_path: string - The path in the Machine where the file will be written. Must be an absolute path.
• raw_value: string - Contains the base64 encoded string of the file contents.
• secret_name: string - The name of the secret containing the base64 encoded file contents.

An example of two files:

        "files": [
            {
                "guest_path": "/path/to/hello.txt",
                "raw_value": "aGVsbG8gd29ybGQK"
            },
            {
                "guest_path": "/path/to/secret.txt",
                "secret_name": "SUPER_SECRET"
            }
        ]

guest: Configure the resources allocated for this Machine. An object with the following options:

• cpu_kind: string (nil) - The type of CPU reservation to make (”shared”, ”performance", and so on).
• gpu_kind: string (nil) - The type of GPU reservation to make.
• host_dedication_id: The ID of the host dedication (group of dedicated hosts) on which to create this Machine. (beta)
• cpus: int (nil) - The number of CPU cores this Machine should occupy when it runs. (default 1)
• kernel_args: Optional array of strings. Arguments passed to the kernel.
• memory_mb: int (nil) - Memory in megabytes as multiples of 256 (default 256)

init: Arguments for init, which is Fly.io’s footprint inside your Machine, and controls how your own code gets run.

• exec: string, string - The command line for the program to run once the Machine boots up. This overrides any other startup command line, either in our API or in your Docker container definition.
• entrypoint: string, string - A command line to override the ENTRYPOINT of your Docker container; another way to define the program that is going to start up when your Machine boots up.
• cmd: string, string - A command line to override the CMD of your Docker container; still another way to define the program that is going to start up when your Machine boots up.
• tty: bool (false) - Allocate a TTY for the process we start up.
• swap_size_mb: int (nil) -Swap space to reserve for the Fly Machine in, you guessed it, megabytes.

metadata: {string:string} ({}) - An object filled with key/value pairs for the Machine metadata. We use metadata internally for routing, process groups, and clusters.

metrics: An optional object defining a metrics endpoint that Prometheus on Fly.io will scrape.

• port: int - Required. The port that Prometheus will connect to.
• path: string - Required. The path that Prometheus will scrape (e.g. /metrics).

mounts: An array of objects that reference previously created persistent volumes. Currently, you may only mount one volume per Machine.

• name: string - Required. The name of the Volume to attach.
• path: string - Required. Absolute path on the Machine where the volume should be mounted. For example, /data.
• extend_threshold_percent: int - The threshold of storage used on a volume, by percentage, that triggers extending the volume’s size by the value of add_size_gb.
• add_size_gb: int - The increment, in GB, by which to extend the volume after reaching the autoextendsizethreshold. Required with autoextendsizeincrement. Required with extend_threshold_percent.
• size_gb_limit: int - The total amount, in GB, to extend a volume. Optional with autoextendsizeincrement. Optional with `extendthreshold_percent`.
• volume: int (nil) - The volume ID, visible in fly volumes list, i.e. vol_2n0l3vl60qpv635d.

processes: An optional array of objects defining multiple processes to run within a Machine. The Machine will stop if any process exits without error.

• entrypoint: An array of strings. The process that will run.
• cmd: An array of strings. The arguments passed to the entrypoint.
• env: An object filled with key/value pairs to be set as environment variables.
• exec: An array of strings. The command to run for Machines in this process group on startup.
• user: string (nil) - An optional user that the process runs under.

restart: Defines whether and how flyd restarts a Machine after its main process exits. Learn more about Machine restart policies. This object has the following options:

• policy: string - Required. One of “no”, “on-failure”, or “always”.
• max_retries: int (nil) - The maximum number of retries when the policy is “on-failure”.

schedule: string (nil) - Optionally one of hourly, daily, weekly, monthly. Runs Machine at the given interval. Interval starts at time of Machine creation

servicescontains an array of objects that define a single network service. Check the Machines networking section for more information.

• protocol: string - Required. tcp or udp. Learn more about running raw TCP/UDP services.
• internal_port: int - Required. Port the Machine listens on.
• concurrency: Control Fly Proxy’s load balancing for this service.
  • type: string - connections (TCP) or requests (HTTP). Default is connections. Determines which kind of event we count for load balancing.
  • soft_limit: int (nil) - Ideal service concurrency. We will attempt to spread load to keep services at or below this limit. We’ll deprioritize a Machine to give other Machines a chance to absorb traffic.
  • hard_limit: int (nil) - Maximum allowed concurrency. The limit of events at which we’ll stop routing to a Machine altogether, and, if configured to do so, potentially start up existing Machines to handle the load.
• ports: MachinePort - An array of objects defining the service’s ports and associated handlers. Options:
  • port: int (nil) - The internet-exposed port to receive traffic on; if you want HTTP traffic routed to 8080/tcp on your Machine, this would be 80.
  • start_port, end-port: int (nil) - Like port`, but allocate a range of ports to route internally, for applications that want to occupy whole port ranges.
  • handlers: Array of protocol handlers for this port. How should the Fly Proxy handle and terminate this connection. Options include http, tcp, tls.
  • force_https: bool (false) - If true, force HTTP to HTTPS redirects.
  • http_options: Fiddly HTTP options (if you don’t know you need them, you don’t), including:
    • compress: bool (false) to enable HTTP compression
    • response: ({“headers”: {string:string}} (nil)) for HTTP headers to set on responses.
  • tls_options: Fiddly TLS options (if you don’t know you need to mess with these, you don’t need to), including:
    • alpn: string, string : ALPN protocols to present TLS clients (for instance, [“h2”, “http/1.1”]).
    • versions: string, string : TLS versions to allow (for instance, [“TLSv1.2”, “TLSv1.3”]).
  • proxy_proto_options: Configure the version of the PROXY protocol that your app accepts. Version 1 is the default.
    • version: A string to indicate that the TCP connection uses PROXY protocol version 2. The default when not set is version 1.
• auto_start: bool (false) - If true, Fly Proxy starts Machines when requests for this service arrive.
• auto_stop: bool (false) - If true, Fly Proxy stops Machines when this service goes idle.
• min_machines_running: int (nil) - When auto_start is true, the minimum number of Machines to keep running at all times in the primary region.

size: A named size for the VM, e.g. performance-2x or shared-cpu-2x. Note: guest and size are mutually exclusive.

standbys: Standbys enable a Machine to be a standby for another. In the event of a hardware failure, the standby Machine will be started. Only for Machines without services. Array of strings representing the Machine IDs of Machines watch (act as standby for).

statics: Optionally serve static files.

• guest_path: string - Required. The path inside the Machines where the files to serve are located.
• url_prefix: string - Required. The URL prefix under which to serve the static files.

stop_config: MachineStopConfig (nil) - Configure graceful shutdown of the Machine.

• signal: string (nil) - the name of the signal to send to the entrypoint process on the Machine to initiate shutdown.
• timeout: int (nil) - how long in nanoseconds to wait, after signaling the entrypoint process, before hard-shutdown of the Machine.

Notes on networking

Machines are closed to the public internet by default. To make them accessible via the associated application, you need to:

• Allocate an IP address to the Fly App
• Add one or more services to the Machine config with ports and handlers, as shown in Create a Machine with services.

For an application with a single Machine, all requests will be routed to that Machine. A Machine in the stopped state will be started up automatically when a request arrives.

For an application with multiple Machines with the same configuration, requests will be distributed across them. Warm-start behavior in this situation is not well-defined now, so should not be relied upon for apps with multiple Machines.

Requests to Machines with mixed configurations will be distributed across Machines whose configurations match the request. For example, if 3 out of 6 Machines have service configurations set to listen on port 80, requests to port 80 will be distributed amongst those 3.

Reaching Machines

Machines can be reached within the private network by hostname, in the format <id>.vm.<app-name>.internal.

For example, to reach a Machine with ID 3d8d413b29d089 on an app called my-app-name, use hostname 3d8d413b29d089.vm.my-app-name.internal.

Machine states

This table explains the possible Machine states. A Machine may only be in one state at a time.