---

name: fly-machines description: Deploy and manage Fly.io Machines - create, start, stop, delete, and monitor containerized apps. Use for deploying containers, managing app instances, and orchestrating multi-tenant workloads. metadata: {"clawdbot":{"emoji":"🪰"}}

fly-machines

Deploy and manage containers on Fly.io using the Machines API.

Setup

1. Get a Fly.io API token from https://fly.io/user/personal_access_tokens
2. Store it:

mkdir -p ~/.config/fly
echo "your_token_here" > ~/.config/fly/token

Or use environment variable:

export FLY_API_TOKEN="your_token_here"

API Reference

Base URL: https://api.machines.dev/v1

All requests require:

FLY_TOKEN=$(cat ~/.config/fly/token 2>/dev/null || echo $FLY_API_TOKEN)
curl -H "Authorization: Bearer $FLY_TOKEN" \
     -H "Content-Type: application/json" \
     "https://api.machines.dev/v1/..."

Apps Management

List all apps:

curl -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps?org_slug=personal"

Create app:

curl -X POST -H "Authorization: Bearer $FLY_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.machines.dev/v1/apps" \
  -d '{
    "app_name": "my-app",
    "org_slug": "personal"
  }'

Get app details:

curl -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app"

Machines

List machines in app:

curl -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/machines"

Create machine:

curl -X POST -H "Authorization: Bearer $FLY_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.machines.dev/v1/apps/my-app/machines" \
  -d '{
    "name": "worker-1",
    "region": "iad",
    "config": {
      "image": "nginx:latest",
      "env": {
        "MY_VAR": "value"
      },
      "services": [{
        "ports": [{"port": 443, "handlers": ["tls", "http"]}],
        "protocol": "tcp",
        "internal_port": 80
      }],
      "guest": {
        "cpu_kind": "shared",
        "cpus": 1,
        "memory_mb": 256
      }
    }
  }'

Get machine:

curl -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/machines/{machine_id}"

Start machine:

curl -X POST -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/machines/{machine_id}/start"

Stop machine:

curl -X POST -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/machines/{machine_id}/stop"

Delete machine:

curl -X DELETE -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/machines/{machine_id}?force=true"

Wait for state:

curl -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/machines/{machine_id}/wait?state=started&timeout=60"

Volumes

List volumes:

curl -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/volumes"

Create volume:

curl -X POST -H "Authorization: Bearer $FLY_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.machines.dev/v1/apps/my-app/volumes" \
  -d '{
    "name": "data_vol",
    "region": "iad",
    "size_gb": 1
  }'

Mount volume to machine:

# Include in machine config:
{
  "config": {
    "mounts": [{
      "volume": "vol_abc123",
      "path": "/data"
    }]
  }
}

Machine Config Options

{
  "name": "my-machine",
  "region": "iad",
  "config": {
    "image": "registry.fly.io/my-app:latest",
    "env": {"KEY": "value"},
    "guest": {
      "cpu_kind": "shared",
      "cpus": 1,
      "memory_mb": 256
    },
    "services": [{
      "ports": [
        {"port": 80, "handlers": ["http"]},
        {"port": 443, "handlers": ["tls", "http"]}
      ],
      "protocol": "tcp",
      "internal_port": 8080
    }],
    "mounts": [{"volume": "vol_id", "path": "/data"}],
    "auto_destroy": false,
    "restart": {"policy": "on-failure"}
  }
}

Regions

Common regions:

• iad - Ashburn, Virginia (US East)
• lax - Los Angeles (US West)
• cdg - Paris
• lhr - London
• nrt - Tokyo
• sin - Singapore
• syd - Sydney

Auto-Stop/Start

Machines automatically stop after idle timeout (default 5 min). They wake on incoming request (~3s cold start).

Disable auto-stop:

{
  "config": {
    "auto_destroy": false,
    "services": [{
      "auto_stop_machines": false,
      "auto_start_machines": true
    }]
  }
}

Secrets

Set secret:

curl -X POST -H "Authorization: Bearer $FLY_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.machines.dev/v1/apps/my-app/secrets" \
  -d '{"MY_SECRET": "secret_value"}'

Secrets are available as environment variables to all machines.

Common Patterns

Deploy a bot instance

FLY_TOKEN=$(cat ~/.config/fly/token)
APP="botspawn"
BOT_ID="user123"

curl -X POST -H "Authorization: Bearer $FLY_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.machines.dev/v1/apps/$APP/machines" \
  -d '{
    "name": "bot-'"$BOT_ID"'",
    "region": "iad",
    "config": {
      "image": "registry.fly.io/botspawn-bot:latest",
      "env": {
        "BOT_ID": "'"$BOT_ID"'",
        "AI_PROVIDER": "anthropic"
      },
      "guest": {"cpu_kind": "shared", "cpus": 1, "memory_mb": 256}
    }
  }'

Scale to zero

Machines auto-stop when idle. To wake:

curl -X POST -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/machines/{id}/start"

Health check

MACHINE=$(curl -s -H "Authorization: Bearer $FLY_TOKEN" \
  "https://api.machines.dev/v1/apps/my-app/machines/{id}")
echo $MACHINE | jq '{state: .state, region: .region, updated: .updated_at}'

CLI Alternative

For interactive use, the flyctl CLI is often easier:

# Install
curl -L https://fly.io/install.sh | sh

# Auth
fly auth login

# Deploy
fly deploy

# List machines
fly machines list -a my-app

# SSH into machine
fly ssh console -a my-app

Notes

• Machines API is separate from the main Fly GraphQL API
• Each machine is an independent VM (Firecracker microVM)
• Volumes are regional and can only attach to machines in same region
• Private networking between machines via .internal DNS
• Logs: fly logs -a my-app or via Fly dashboard