Fly Machines prepared hosts (preview)

The optional @devctl/provider-fly package manages a prepared persistent Docker host through the official Machines REST API. It appears in the same cloud-host picker as other managed hosts, with its setup requirements visible. Creation is gated until an operator configures that profile; an arbitrary application OCI image is not treated as a working devctl host.

Fly can run a Docker daemon in a Machine: Fly's own remote builder runs dockerd, and current flyctl provisioning launches that image with a persistent /data volume. The Machines API has no invented privileged flag in this integration. The host's Docker daemon supplies the existing runtime's isolated rootless sidecars in the ordinary way.

Explicit prerequisites

Prepare these resources in your own Fly account before using this adapter:

Build/publish the image for Fly's target architecture, for example linux/amd64, using your normal registry authentication. The recipe installs Ubuntu 24.04, Docker Engine, Buildx, Compose, SSH, curl, git and sudo. Its entrypoint supervises Docker and SSH directly; systemd is not required for Project containers. Control Room native Host execution, which requires systemd, is unsupported on this profile. Use the normal Docker execution mode there. No native session survives a full Machine stop/start; saved disk state is separate from live memory.

Configure the existing cloud state

Create providers/fly.json inside your private devctl cloud-state directory (normally ~/.config/devctl/cloud on the machine running ./devctl). This directory is already mounted into the one-shot provisioner; no new secret or transport channel is introduced. The JSON contains only resource references:

{
  "profile": "devctl-docker-host-v1",
  "app": "your-dedicated-app",
  "volumeId": "vol_yourvolumeid",
  "sshHost": "your-dedicated-app.fly.dev",
  "sshPort": 22,
  "image": "registry.fly.io/your-dedicated-app@sha256:REPLACE_WITH_ACTUAL_64_HEX_DIGEST"
}

Supply a suitably scoped FLY_API_TOKEN privately, or use devctl's hidden token prompt. The API token travels on stdin, never in this profile or the Machine's environment. Only the generated public SSH key is passed to the host image. No browser login, app creation, public IP allocation or volume purchase runs implicitly. The profile string is explicit acknowledgement of this image/runtime contract, not a claim that devctl independently verified your account deployment.

./devctl cloud regions fly
./devctl cloud create fly my-fly-host
./devctl cloud status my-fly-host
ssh my-fly-host

Supported sizes are shared-cpu-2x (4 GiB), shared-cpu-4x (8 GiB, default) and shared-cpu-8x (16 GiB). The region comes from the actual volume; a conflicting --region is rejected before creating a Machine. --image prepared-host selects the configured immutable digest. Shared installer checks, including docker info, must pass before a host is enrolled. Unsupported kernel/user-namespace/cgroup capabilities fail readiness; they do not select another runtime.

Persistence, recovery and lifecycle

The recipe requires /data to be a real mount. It persists /root, /home, /var/lib/devctl, Docker data and SSH host keys on that volume before starting services. Account homes, credentials, Project checkouts and managed container storage therefore do not rely on Fly's replaceable root filesystem. Manually installed host packages or files elsewhere in rootfs are not persistent; include required host tools in the immutable image. Fly Volumes are local to a region/host and are not an automatic replicated backup. See volume semantics.

Creation saves a stable intent before its first API call. A retry first lists the dedicated app and adopts only the exact unique Machine name with the same creation UUID and volume metadata. A saved accepted Machine ID is read directly. A conflicting name, occupied app or attached volume fails closed. The adapter does not invent an undocumented Machines Idempotency-Key contract. HTTP errors retain recovery state and omit response bodies/credentials from diagnostics.

./devctl cloud stop my-fly-host
./devctl cloud resume my-fly-host
./devctl cloud destroy my-fly-host

Stop sends SIGTERM with a 60-second grace period and waits for the observed stopped state. Resume waits for running state. Automatic service stop/start is disabled so an incidental SSH connection cannot silently resume a billable host. Suspend/memory restore, snapshots and public application port management are not exposed by this adapter.

Destroy deletes only the managed Machine. The operator-owned app, IP and volume remain, including stored credentials and Projects, and can remain billable. Destroy does not claim disk erasure. Review and erase those retained resources in Fly separately when intended; removing this optional package does not clean them up. See current official pricing, including stopped rootfs, volume, backup and IP charges.

Verification

API tests use real documented JSON formats, including bodyless lifecycle responses, ownership collisions, volume prerequisites, recovery, auth failures and confirmed Machine deletion. An optional live test reads exactly one existing managed Machine when explicitly enabled; it never provisions or changes anything.

The host recipe was built locally and checked with actual key-only SSH and a nested Docker daemon. Its opt-in local smoke test also checks the exact managed rootless Docker sidecar and cold replacement with the same volume:

docker build -t devctl-fly-host:verification packages/provider-fly/host-image
DEVCTL_TEST_FLY_HOST_IMAGE=1 node packages/provider-fly/host-image/smoke.mjs

This local check runs isolated temporary Docker containers and a temporary volume; it is not a Fly deployment test. Actual Fly account capacity, AMD64 image startup, network routing, kernel support and full devctl enrollment are unverified without an explicitly prepared paid host. Sprites is not enabled: its exec API alone does not establish the Docker and persistence guarantees this runtime requires.