Skip to content

sb-dev/openquant / .agents/skills/fly

Operate 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.

FileKindSize
SKILL.mdskill md15.1 KB
references/configure.mdmarkdown9.4 KB
references/deploy.mdmarkdown7.1 KB
references/launch.mdmarkdown5.4 KB
references/machines.mdmarkdown6.6 KB
references/networking.mdmarkdown5.9 KB
references/operate.mdmarkdown6.7 KB
references/postgres.mdmarkdown6.6 KB
references/safety.mdmarkdown6.0 KB
references/scale.mdmarkdown5.3 KB
references/secrets.mdmarkdown3.9 KB
references/setup.mdmarkdown6.8 KB
references/sprites-cli.mdmarkdown9.3 KB
references/sprites.mdmarkdown17.4 KB
references/storage.mdmarkdown3.1 KB
references/tools.mdmarkdown14.4 KB
references/volumes.mdmarkdown4.6 KB

references/volumes.md

View on GitHub
# Volumes and snapshots

A volume is persistent NVMe storage in one region, attached to at most one
Machine. Fly volumes are not shared or replicated: redundancy means more
Machines with their own volumes and application-level replication or a
database that does it for you. Snapshots are the backup mechanism.

## Inspect

```bash
fly volumes list -a <app> --json                # id, name, region, size, attached Machine, state
fly volumes show <id> -a <app>
fly volumes snapshots list <volume-id> -a <app>
```

MCP: `list_volumes` (hides deleting volumes unless `include_destroyed`; with
`summary: true` the byte and block statistics are omitted, not zero),
`get_volume`, `list_volume_snapshots`.

## Create

```bash
fly volumes create <name> -a <app> -r <region> -s 10            # GB; default 1
fly volumes create <name> -a <app> -r <region> -s 10 -n 2       # two volumes (two Machines)
fly volumes create <name> -a <app> -r <region> --snapshot-id <id>   # restore from a snapshot
fly volumes create <name> -a <app> -r <region> --snapshot-retention 14
fly volumes create <name> -a <app> -r <region> --vm-size performance-2x  # place for that Machine class
```

Flags: `--require-unique-zone` (default true) spreads same-named volumes
across hardware zones; `--scheduled-snapshots` (default true) enables daily
snapshots; `--no-encryption` disables at-rest encryption (do not do this
without being asked). Volumes are billable from creation; confirm size, region
and count.

The `name` must match `[[mounts]] source` in `fly.toml`, and the mount's
`destination` is where it appears in the Machine. `fly launch --volume
name:/path` and `fly deploy` create volumes when `[[mounts]]` names one that
does not exist yet, sized by `initial_size`.

MCP: `create_volume` (billable; does not restore or fork, which need separate
source-resource authorization). After an uncertain response, list volumes
before retrying.

## Resize, fork, update

```bash
fly volumes extend <id> -a <app> -s 20            # grow only; cannot shrink
fly volumes fork <id> -a <app> [--name <n>] [--region <code>]   # new volume with a copy of the data
fly volumes update <id> -a <app> --scheduled-snapshots=true --snapshot-retention 10
```

Extending grows charges and may need a Machine restart for the filesystem to
see the space, depending on the image. Automatic growth is configured in
`fly.toml` under `[[mounts]]` (`auto_extend_size_threshold`, `_increment`,
`_limit`), not on the volume. MCP: `extend_volume` (its result, like
`create_volume`'s, reports zero statistics; read `get_volume` for usage),
`update_volume` (read current settings and preserve the rest).

## Snapshots

```bash
fly volumes snapshots create <volume-id> -a <app>
fly volumes snapshots list <volume-id> -a <app>
fly volumes create <name> -a <app> -r <region> --snapshot-id <snapshot-id>   # restore into a new volume
fly machine clone <id> -a <app> --from-snapshot last                         # new Machine on a restored volume
fly scale count 2 --from-snapshot last -a <app>
```

Snapshot creation is asynchronous; it may return before an ID exists. List
until the snapshot's status is `created`; while `running`, its `created_at`
reads `0001-01-01T00:00:00Z` and sizes are placeholders. Do not call it a
backup until it completes. Daily scheduled snapshots are kept for
`snapshot_retention` days (default 5, max 60). Restoring always creates a new
volume; there is no in-place restore.

MCP: `create_volume_snapshot` (attached, ready volume only), then
`list_volume_snapshots` for the ID and status.

## Destroy

```bash
fly volumes destroy <id> -a <app> [-y]
```

Irreversible. The volume must be detached: stop and destroy the Machine, or
`fly machine update` it without the mount, first. Confirm the exact volume ID,
check `fly volumes snapshots list` for a recent snapshot, and say what data is
lost. MCP: `delete_volume`, which also requires the volume to be detached; if
the detach step is unavailable over MCP, explain the prerequisite rather than
forcing it.

## Scaling with volumes

- One volume per Machine. `fly scale count` reuses unattached volumes in the
  region first, then creates empty ones (`--with-new-volumes` forces new).
- Scaling down detaches; it never deletes.
- `canary` and `bluegreen` deploy strategies cannot be used with mounts.
- Growing to a new region means a new empty volume there; copy data yourself.

## Practical notes

- Mount paths: `/data` by convention; never `/`.
- Databases on volumes: Fly's unmanaged Postgres uses volumes; Managed
  Postgres does not expose them ([postgres.md](postgres.md)).
- A Sprite checkpoint and a volume snapshot are unrelated; neither protects
  the other's data.

Checked against flyctl v0.4.123 and mcp.fly.io on 2026-10-28.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall