Multi-container Machines

Fly Machines support running multiple containers per virtual machine using the containers array. This feature is currently available through the Machines API and requires using Pilot as the init system. This capability is useful for co-locating services such as your application server, log shippers, metrics collectors, or sidecars.

Common Sidecar Use Cases

Sidecars are a powerful way to co-locate supporting services alongside your application. This pattern is especially helpful for apps built with multi-tenant or per-user architectures, such as AI agents, dev environments, or SaaS dashboards. Some practical uses include:

Metrics and Logs: Run a Prometheus exporter or a log shipper like Vector to forward application logs or metrics without bundling that logic into your app.
Secrets Agents: Use a sidecar to fetch secrets from a provider like Vault or cloud metadata services. This keeps your app container lightweight and secure.
Load Smoothing: Use nginx or Envoy as a reverse proxy for rate limiting, retries, or graceful error handling. This is great for handling bursts in traffic or external API instability.
Storage or Sync Layers: Mount and manage local state using sidecars like LiteFS or file sync daemons. You can keep persistent logic separated from your app’s logic.
AI Agents or Workers: For agent-based or queued workloads, you can spin up workers or schedulers in separate containers and coordinate them using depends_on.

These patterns mirror what we’ve seen from customers building production systems on Fly Machines with Pilot and the containers array. Each container runs in its own isolated process tree, and Pilot ensures the startup order and health status are respected. While containers share the same kernel and VM, they are isolated at the process and filesystem level.

Defining Containers

When creating a Machine via the API, you can specify a containers array, each containing a ContainerConfig. Each container can have its own image, environment variables, health checks, startup commands, attached files, and dependencies. flyd (our in-house orchestrator) handles pulling images and making them accessible to Pilot, the init system responsible for running the containers and managing their lifecycle. Pilot builds a dependency graph using container startup conditions and runs containers accordingly.

Example Configuration

{
  "containers": [
    {
      "name": "my-app",
      "image": "registry.fly.io/my-app:latest",
      "env": {
        "PORT": "8080"
      },
      "healthchecks": [
        {
          "http": {
            "port": 8080,
            "method": "GET",
            "path": "/health",
            "scheme": "http"
          },
          "interval": 10,
          "timeout": 5,
          "grace_period": 5,
          "success_threshold": 2,
          "failure_threshold": 3
        }
      ]
    },
    {
      "name": "log-shipper",
      "image": "registry.fly.io/log-shipper:latest",
      "env": {
        "LOG_LEVEL": "info"
      },
      "depends_on": [
        {
          "name": "my-app",
          "condition": "healthy"
        }
      ]
    }
  ]
}

In this configuration, the log-shipper container depends on the my-app container being healthy before starting.

Container Dependencies

You can define dependencies between containers using the depends_on field. Supported conditions include:

"depends_on": [
  {
    "name": "sidecar1",
    "condition": "healthy"
  }
]

Valid values for condition:

healthy: Container will wait until the dependency container passes its health checks.
started: Container will start as soon as the dependency container has started.
exited_successfully: Container will wait until the dependency container has exited with a success code.

Internally, Pilot models these dependencies as a directed graph and walks it to orchestrate the correct container startup order.

Health Checks

Each container specifies its own health checks. The system supports different types of health checks: TCP health checks: Checks if a port is accepting connections

"tcp": {
  "port": 6379
}

HTTP health checks: Makes HTTP requests to an endpoint

"http": {
  "port": 80,
  "method": "GET",
  "path": "/",
  "scheme": "http"
}

Exec health checks: Runs a command inside the container

"exec": {
  "command": ["sh", "-c", "pg_isready -U postgres"]
}

Health Check Configuration Options

name: string - Unique identifier for the health check
interval: int - How often to run the check, in seconds
grace_period: int - Time in seconds to wait after container starts before checks begin
timeout: int - Maximum time in seconds to wait for a check to complete
success_threshold: int - Number of consecutive successful checks required to change status to healthy
failure_threshold: int - Number of consecutive failed checks before marking as unhealthy

Security Considerations

Containers in a Machine share the same kernel and VM, but are isolated at the process and filesystem level. Failures in one container won’t directly crash others, but they don’t provide the same level of isolation as across VMs.

Deploying Multi-container Machines

There are several ways to deploy multi-container machines on Fly.io. Choose the method that best fits your workflow:

Using Docker Compose

If you already have a Docker Compose setup, you can deploy it to Fly Machines without rewriting your configuration. Fly builds and runs Compose services as containers within a single Machine.

Requirements

You need flyctl v0.3.152 or later:

fly version

If you’re behind, update with fly version update.

Configuration

Add a [build.compose] section to your fly.toml:

[build.compose]

Fly auto-detects Compose files using the standard lookup order: compose.yaml, compose.yml, docker-compose.yaml, docker-compose.yml. If your file has a different name, specify it:

[build.compose]
file = "docker-compose.prod.yml"

Routing traffic

Set internal_port in your fly.toml [[services]] or [http_service] block to match the port exposed by the container that should receive traffic. Only one container handles inbound requests from the Fly proxy.

[http_service]
  internal_port = 8080
  force_https = true

Example

A web service with a Redis sidecar, both running in the same Machine. fly deploy builds the web service from a Dockerfile in your project directory; redis runs as a pre-built sidecar. Dockerfile:

FROM nginxdemos/hello:plain-text

compose.yml:

services:
  web:
    build: .
    ports:
      - "80:80"

  redis:
    image: redis:latest

fly.toml:

app = "my-compose-app"
primary_region = "ord"

[build.compose]

[http_service]
  internal_port = 80
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true

[[vm]]
  size = "shared-cpu-1x"
  memory = "512mb"

Deploy with:

fly deploy

The web container handles inbound traffic on port 80, and the redis container runs alongside it as a sidecar. Your application code can reach Redis at localhost:6379 because both containers share the same network namespace inside the Machine.

Warning: Fly ignores volumes: declarations in your Compose file and prints Warning: Could not read volume file... at deploy time. The deploy still succeeds, but any data your containers write is stored on an ephemeral overlay that’s wiped on restart or redeploy. For persistent storage, attach a Fly Volume and mount it via [mounts] in fly.toml.

Limitations

Exactly one buildable service. fly deploy requires exactly one service in the Compose file to specify build. All other services must use pre-built images.
Secrets are global. Secrets set with fly secrets are available to every container in the Machine. You can’t scope a secret to a single service.
Environment variable conflicts. Fly injects runtime environment variables (like FLY_APP_NAME, PRIMARY_REGION, etc.) into all containers. These can overwrite values you define in your Compose file’s environment block.

Using the Machines API

You can create multi-container Machines by sending a POST request to the Machines API. For example, using curl:

curl -X POST "https://api.machines.dev/v1/apps/<your-app-name>/machines" \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d @api-config.json

Here, the api-config.json file contains the request body for creating a Machine. Unlike the flyctl examples in the next sections, the API expects the JSON body to have a config wrapper with the containers array nested inside:

{
  "config": {
    "containers": [...],
    ...
  }
}

The config object can also include other Machine fields like guest and services. Refer to the Machines API documentation for complete configuration options.

Using `fly machine run`

Create a multi-container Machine by passing a JSON configuration file (e.g., cli-config.json) to fly machine run:

fly machine run --machine-config cli-config.json

The file should define containers at the root level, alongside any additional Machine configuration:

{
  "containers": [...],
  ...
}

You can also pass Machine configuration options from the command line:

fly machine run --machine-config cli-config.json \
  --autostart=true --autostop=suspend \
  --port 80:8080/tcp:http --port 443:8080/tcp:http:tls \
  --vm-cpu-kind shared --vm-cpus 1 --vm-memory 256

Note: When using --machine-config, your JSON file must include a containers array with at least one container that specifies an image.

Using `fly launch` & `fly deploy`

Starting with flyctl v0.3.147, you can run multiple containers using fly deploy. This example demonstrates using a nginx container as a rate limiter and a custom app container.

1. Create `cli-config.json`

{
  "containers": [
    {
      "name": "nginx",
      "image": "nginx:latest",
      "files": [
        {
          "guest_path": "/etc/nginx/conf.d/default.conf",
          "local_path": "nginx.conf"
        }
      ],
      "depends_on": [
        {
          "name": "echo",
          "condition": "healthy"
        }
      ]
    },
    {
      "name": "echo",
      "image": "ealen/echo-server",
      "healthchecks": [
        {
          "exec": {
            "command": ["wget", "-q", "--spider", "http://localhost"]
          }
        }
      ]
    }
  ]
}

2. Update fly.toml

Note: flyctl version 0.3.147 or later is required to use this config

[experimental]
machine_config = 'cli-config.json'
container = 'echo'

[http_service]
internal_port = 8080

The container value determines which container will be replaced by your app image built by fly deploy.

3. Run fly deploy

fly deploy

This builds and replaces the echo container, runs both containers on the same machine, and configures traffic through nginx. You can also inline the machine_config in your fly.toml using triple quotes. The first character inside the string must be {:

machine_config = '''{
  "containers": [
    …
  ]
}'''

Example Configurations

Here are some practical examples of multi-container setups you can use as a starting point:

Rate Limiter Sidecar

To mitigate excessive traffic, you can run an nginx container as a sidecar to limit requests per second using the ngx_http_limit_req_module. Below is a simplified container configuration that enables rate limiting:

{
  "containers": [
    {
      "name": "nginx",
      "image": "nginx:latest",
      "files": [
        {
          "guest_path": "/etc/nginx/conf.d/default.conf",
          "raw_value": "bGltaXRfcmVxX3pvbmUgJGJpbmFyeV9yZW1vdGVfYWRkciB6b25lPW15X3pvbmU6MTBtIHJhdGU9MXIvczsKCnNlcnZlciB7CiAgbGlzdGVuIDgwODA7CgogIGxvY2F0aW9uIC8gewogICAgbGltaXRfcmVxIHpvbmU9bXlfem9uZTsKICAgIHByb3h5X3Bhc3MgaHR0cDovL2xvY2FsaG9zdDo4MDsKICB9Cn0="
        }
      ]
    },
    {
      "name": "echo",
      "image": "ealen/echo-server"
    }
  ]
}

When attaching files to containers, the raw_value field must contain base64-encoded content. The nginx configuration shown in the JSON above corresponds to this configuration:

limit_req_zone $binary_remote_addr zone=my_zone:10m rate=1r/s;

server {
  listen 8080;

  location / {
    limit_req zone=my_zone;
    proxy_pass http://localhost:80;
  }
}

When the container starts, Fly will decode this value and write the original configuration to the specified guest_path. To complete this configuration, you should also include:

A services block that exposes internal port 8080 for Fly Proxy
A guest block specifying resources like CPU and memory
Optionally, depends_on fields or health checks if you want nginx to wait for the app

LiteFS Sidecar with Health Checks

You can also run LiteFS as a sidecar with a health check configured to ensure it’s operating correctly:

{
  "containers": [
    {
      "name": "litefs",
      "image": "flyio/litefs:latest",
      "env": {
        "LITEFS_DIR": "/data",
        "LITEFS_CONFIG": "/etc/litefs.yml"
      },
      "healthchecks": [
        {
          "http": {
            "port": 8080,
            "method": "GET",
            "path": "/info",
            "scheme": "http"
          },
          "grace_period": 500,
          "interval": 1000,
          "timeout": 1000,
          "success_threshold": 1,
          "failure_threshold": 5
        }
      ]
    }
  ]
}

For more information about container configuration options, refer to the Machines API documentation.

​Common Sidecar Use Cases

​Defining Containers

​Example Configuration

​Container Dependencies

​Health Checks

​Health Check Configuration Options

​Security Considerations

​Deploying Multi-container Machines

​Using Docker Compose

​Requirements

​Configuration

​Routing traffic

​Example

​Limitations

​Using the Machines API

​Using fly machine run

​Using fly launch & fly deploy

​1. Create cli-config.json

​2. Update fly.toml

​3. Run fly deploy

​Example Configurations

​Rate Limiter Sidecar

​LiteFS Sidecar with Health Checks

Common Sidecar Use Cases

Defining Containers

Example Configuration

Container Dependencies

Health Checks

Health Check Configuration Options

Security Considerations

Deploying Multi-container Machines

Using Docker Compose

Requirements

Configuration

Routing traffic

Example

Limitations

Using the Machines API

Using `fly machine run`

Using `fly launch` & `fly deploy`

1. Create `cli-config.json`

2. Update fly.toml

3. Run fly deploy

Example Configurations

Rate Limiter Sidecar

LiteFS Sidecar with Health Checks