sb-dev/openquant / .agents/skills/fly
fly
FlaggedOperate Fly.io: sign in or sign up, launch and deploy apps, edit fly.toml, scale Machines across regions, manage volumes, secrets, IP addresses, certificates and custom domains, Managed Postgres, Tigris object storage and Upstash Redis, read logs and status, troubleshoot failed deploys and health checks, and run builds, tests or agents in Sprites, Fly's persistent remote Linux environments. Use this skill whenever the user mentions Fly, Fly.io, flyctl, fly.toml, Machines, deploying, scaling, regions, volumes, secrets, Postgres or MPG on Fly, Sprites, sprite-env, sprites.dev, a sandbox or remote build environment, or infrastructure operations, even if they don't say "Fly" explicitly. Also invoke it to set up Fly agent tooling (skills, MCP, login) or when the user asks to be signed up or onboarded.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.1 KB |
| references/configure.md | markdown | 9.4 KB |
| references/deploy.md | markdown | 7.1 KB |
| references/launch.md | markdown | 5.4 KB |
| references/machines.md | markdown | 6.6 KB |
| references/networking.md | markdown | 5.9 KB |
| references/operate.md | markdown | 6.7 KB |
| references/postgres.md | markdown | 6.6 KB |
| references/safety.md | markdown | 6.0 KB |
| references/scale.md | markdown | 5.3 KB |
| references/secrets.md | markdown | 3.9 KB |
| references/setup.md | markdown | 6.8 KB |
| references/sprites-cli.md | markdown | 9.3 KB |
| references/sprites.md | markdown | 17.4 KB |
| references/storage.md | markdown | 3.1 KB |
| references/tools.md | markdown | 14.4 KB |
| references/volumes.md | markdown | 4.6 KB |
references/machines.md
View on GitHub# Machines
A Machine is one Firecracker VM running one image, in one region, in one
process group. `fly deploy` manages app Machines as a group; `fly machine`
commands and the Machine MCP tools act on individual Machines. Both paths need
the exact Machine ID, from `fly machine list` or `list_machines`.
## Inspect
```bash
fly machine list -a <app> --json # IDs, state, region, image, size
fly machine list -a <app> -q # IDs only
fly machine status <id> -a <app> # state, events, checks
fly machine status <id> -a <app> --display-config # full config as JSON (may include env values)
fly logs -a <app> -m <id> # one Machine's logs
```
MCP: `list_machines`, `get_machine` (lifecycle summary, no config),
`list_machine_events`, `wait_for_machine_state`. Configuration, history,
processes and metadata (`get_machine_configuration`, `list_machine_versions`,
`list_machine_processes`, `get_machine_metadata*`) need the
`fly:machines:sensitive:read` grant because env, files and arguments can hold
secrets; request them only when the task needs them and summarize
selectively. `list_machine_processes` includes kernel threads with empty
commands; report the named processes.
Machine states: `created`, `starting`, `started`, `stopping`, `stopped`,
`suspending`, `suspended`, `replacing`, `destroying`, `destroyed`. A service
with autostop may have stopped a Machine minutes after it started; check the
state before assuming a fault.
## Lifecycle
```bash
fly machine start <id> [<id>...] -a <app>
fly machine stop <id> -a <app> [--signal SIGTERM --timeout 30]
fly machine restart <id> -a <app> [--skip-health-checks] [--force]
fly machine suspend <id> -a <app> # snapshot memory; resumes faster than stop
fly machine kill <id> -a <app> # SIGKILL, no cleanup
fly machine cordon <id> -a <app> # pull from proxy routing, keep running
fly machine uncordon <id> -a <app>
fly machine wait <id> -a <app> --state started # block until a state
fly machine destroy <id> -a <app> # must be stopped or suspended unless --force
fly machine destroy --image <hash> -a <app> # every Machine running that image
```
MCP: `start_machine`, `stop_machine`, `restart_machine`, `suspend_machine`,
`signal_machine`, `cordon_machine`, `uncordon_machine`, `delete_machine`
(never enables `force` implicitly). Stopping a Machine whose config has
`auto_destroy` set destroys it. Explain disruption before any of these on a
production app; the plugin hook asks.
`delete_app` / `fly apps destroy` is broader than one Machine: it removes
every Machine, volume, IP and certificate the app owns. Inspect first.
## Create and change
```bash
fly machine run <image> [command] -a <app> -r <region> \
--vm-size shared-cpu-1x -e KEY=VAL -p 443:8080/tcp:http:tls \
--volume <vol>:/data --autostop stop --autostart --name <name>
fly machine run <image> --rm -a <app> -- <one-off command> # ephemeral task Machine
fly machine update <id> -a <app> --image <ref> # new image, same config
fly machine update <id> -a <app> --vm-memory 1024 --autostop suspend
fly machine update <id> -a <app> -C "<command>" --entrypoint <path>
fly machine update <id> -a <app> --file-local /etc/app.yml=./app.yml
fly machine update <id> -a <app> --metadata key=value
fly machine update <id> -a <app> --schedule hourly # cron-like Machines
fly machine clone <id> -a <app> [--region <code>] [--name <n>] [--attach-volume <vol>:/data] [--from-snapshot last]
fly machine clone <id> -a <app> --standby-for <id> # standby that starts if the source fails
fly machine place -a <app> --region <code> --count 3 # dry-run placement
```
Machines made with `fly machine run` are **unmanaged by `fly deploy`**. They
suit cron jobs, one-off tasks, standbys and experiments. For app Machines,
change `fly.toml` and deploy instead, so the config and the Machines agree.
MCP: `create_machine` (billable; starts unless `skip_launch`; if the response
is lost, look for the Machine before retrying), `update_machine_metadata`
(merges keys, needs `machine_version`; stale version is a conflict, so reread
and reassess rather than loop), `set_machine_metadata_key`,
`delete_machine_metadata_key`, `get_machine_memory`,
`set_machine_memory_limit`, `reclaim_machine_memory`. General Machine
configuration updates are not exposed over MCP; use `fly machine update`.
## Execute a command
```bash
fly machine exec <id> "<command>" -a <app> [--timeout 60] [--container <name>]
fly ssh console -a <app> --machine <id> -C "<command>" # when exec needs a shell or TTY
```
MCP `exec_machine_command` takes `app_name`, `machine_id` and `body.command`
as an argv array, for example `{"command": ["uname", "-a"]}`. There is no
implicit shell; pass `["sh", "-c", "..."]` only when shell syntax is needed,
and never serialize an argv into one string. The Machine must be `started`;
exec against a stopped Machine currently reports a `conflict` saying the
resource "changed or is leased", so check `get_machine` before suspecting a
lease. The result carries `exit_code`, `stdout` and `stderr`; report the exit
code. A command can read or change production data however diagnostic it
looks; confirm first and keep sensitive output out of the reply.
## Leases
A lease is an exclusive write lock on a Machine, used by deploy tooling.
```bash
fly machine leases view <id> -a <app>
fly machine leases clear <id> -a <app> # only when you know the holder is gone
```
MCP: `get_machine_lease` (answers `Resource not found` when no lease is held;
confirm the Machine exists with `get_machine`), `create_machine_lease`
(returns a nonce; keep it private, renew with the same nonce),
`release_machine_lease` (exact nonce). While a lease is held, Machine changes
without its `lease_nonce` are refused; the server currently reports that as
`outcome_unknown` even though nothing was applied. Inspect, then repeat with
the nonce if you hold it. Never release another operator's lease.
## Volumes and Machines
A volume attaches to one Machine. `fly machine clone` creates a new empty
volume for a Machine that has one (or restores from a snapshot with
`--from-snapshot`). `fly machine destroy` leaves the volume behind. See
[volumes.md](volumes.md).
## Verify and report
After any change: `fly machine status <id>` or `get_machine`, then the
relevant runtime check (`fly logs -m <id>`, an HTTP probe, `fly checks list`).
Report the Machine ID, region, state, and what you observed. After a timeout,
inspect before retrying: the original call may have succeeded.
Checked against flyctl v0.4.123 and mcp.fly.io on 2026-10-28.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |