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:
- A dedicated Fly app with no other Machines. A public raw TCP SSH service must route solely to this host, rather than balancing unrelated Machines.
- One unattached persistent Fly Volume, in the desired region, with enough space for Projects, account homes and Docker images. The adapter does not purchase, format, clone, snapshot or automatically delete a volume.
- A public SSH hostname/address and TCP port backed by Fly networking. A dedicated IPv4 is a straightforward option; its separate charge is an operator choice. Fly's private 6PN address is not a public SSH endpoint, and shared HTTP/TLS ports are not a raw SSH service. No WireGuard proxy is silently installed.
- An immutable OCI digest built from the prepared host recipe, available to that app. Publish it explicitly; devctl neither uploads your source to a registry nor creates a Fly app to publish an image.
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.