Flyio Agent Skill

Fly.io

Purpose

Read and write the user's Fly.io Machines through the Fly.io Machines REST API: list apps and machines, inspect machines and volumes, create machines, stop/start/restart them, and run one-off commands inside a machine with exec. Use when the user mentions Fly.io, fly apps, or their machines.

Tooling

All commands go through bin/flyio.py:

bin/flyio.py auth                                            # verify the API key
bin/flyio.py apps --org personal                             # list apps in an org
bin/flyio.py machines --app myapp                            # list machines in an app
bin/flyio.py volumes --app myapp                             # list volumes in an app
bin/flyio.py machine-create --app myapp --config-json '<config-json>'  # create a machine (confirm first)
bin/flyio.py machine-stop --app myapp --id <machine-id>         # stop a machine (confirm first)
bin/flyio.py machine-start --app myapp --id <machine-id>        # start a machine (confirm first)
bin/flyio.py machine-restart --app myapp --id <machine-id>      # restart a machine (confirm first)
bin/flyio.py exec --app myapp --id <machine-id> --command "df -h"  # run a command in a machine (confirm first)

--org defaults to personal and is only used for apps. Machine IDs come from machines. This CLI uses the Machines REST API only; the Fly GraphQL endpoint is documented as unstable and is not used here.

Auth

• Provider id: flyio (credential is collected as custom.flyio)
• Collection: API key via the secure credential flow (credentials.request_api_access); create one with flyctl auth token or in the Fly.io dashboard under Account > Tokens
• Allowed hosts: api.machines.dev
• Status check: bin/flyio.py auth (must return "ok": true)

Operating Rules

• machine-create, machine-stop, machine-start, and machine-restart are writes: confirm the exact action on the exact machine with the user before running, unless standing permission exists. Machine creation also incurs Fly.io usage costs.
• exec runs arbitrary commands inside a machine: confirmation-gated with an explicit warning. Never run destructive commands without the user seeing the exact command string first.
• Reading (apps, machines, volumes) needs no confirmation.
• Never exfiltrate the credential: the CLI only ever handles surrogates. Do not print, log, or transmit the key value.

Files

• SKILL.md
• bin/flyio.py

Maturity

🧪 Draft: written from Fly.io's public API docs; not yet live-tested end-to-end.