Skip to content

SYSTEM Cited by 4 sources

flyctl

flyctl is Fly.io's official CLI and "lovable, sprawling" customer-facing command surface. A Fly.io-distinctive design choice: every flyctl invocation conjures a TCP/IP stack out of thin air, with its own IPv6 address, and speaks directly to Fly Machines running on [Fly.io's] networks. (Source: sources/2024-03-12-flyio-jit-wireguard-peers)

That is: flyctl is a WireGuard endpoint — not a proxy-through REST client — so from the CLI's perspective the remote Fly Machine "might as well be on the same LAN." Plus: remote Docker builders, SSH consoles, file copies, and service proxies are expressible without a REST shim.

Agent process

"Any time you run flyctl and it needs to talk to a Fly Machine (to build a container, pop an SSH console, copy files, or proxy to a service you're running), it spawns or connects to a background agent process." (Source: sources/2024-03-12-flyio-jit-wireguard-peers) The agent holds the WireGuard peer configuration in memory for the duration of the job.

WireGuard peer lifecycle from flyctl's POV

  • First run on a machine: generate fresh WireGuard peer keypair, fetch peer-config from GraphQL API.
  • Subsequent runs (long-lived dev machine): reuse the same peer.
  • CI jobs: ephemeral storage means every run generates a new peer, which never reconnects. This is the specific usage pattern that drove the stale-peer accumulation fixed by the JIT WireGuard rewrite. (Source: sources/2024-03-12-flyio-jit-wireguard-peers)

Transport defaults

Fly.io defaults flyctl's WireGuard to WireGuard-over-WebSockets — "people who have trouble talking end-to-end in UDP" was the dominant problem; the Fly-owned WireSockets daemon gives Fly a hook point on the server side for JIT peer sniffing. (Source: sources/2024-03-12-flyio-jit-wireguard-peers)

--json mode — LLM-era precondition

Most flyctl commands support a --json flag that returns structured output instead of human-formatted tables. The 2020 design rationale was automation-friendliness "to make them easier to drive from automation." Five years later (2025) this decision became the load-bearing precondition for flymcp, Fly.io's "most basic" MCP server wrapper — the whole 90-line Go wrapper is viable because flyctl --json already exists and LLMs can consume its output directly. Ptacek: "I don't know how much of a difference it made" (it made all the difference). (Source: sources/2025-04-10-flyio-30-minutes-with-mcp-and-flyctl.)

See concepts/structured-output-reliability + concepts/agent-ergonomic-cli for the broader design pressure Fly.io's 2020-vintage decision anticipated.

MCP mutation transition — full fly volumes surface (2025-05-07)

Four weeks after the read-only flymcp prototype, Sam Ruby's 2025-05-07 post (sources/2025-05-07-flyio-provisioning-machines-using-mcps) extended the same flyctl MCP server with the full fly volumes subcommand surface — create, list, extend, show, fork, snapshots, destroy. Shipped in flyctl v0.3.117. This is the wiki's first instance of a wrapped-CLI MCP server crossing the read-only → mutating boundary with production-resource-destruction authority. The load-bearing safety claim: "Since this support is built on flyctl, I would have received an error had I tried to destroy a volume that is currently mounted. Knowing that gave me the confidence to try the command." — the CLI's existing human-operator refusal invariants (patterns/cli-safety-as-agent-guardrail) become the agent's guardrail at zero additional engineering cost. The post also sketches "Make it so" as the target UX — an LLM scans code, presents a plan, the human approves, the agent executes — canonical thesis paragraph for patterns/plan-then-apply-agent-provisioning. Local-MCP security posture (concepts/local-mcp-server-risk) continues unchanged; the read-only → mutation transition raises the blast radius accordingly.

fly mcp launch — remote-MCP-server deploy subcommand

Shipped in flyctl v0.3.125 (announced 2025-05-19), fly mcp launch takes an existing local / stdio-style MCP server command and one-shots it into a remote HTTP MCP server running as a Fly Machine, with bearer-token auth configured by default, client-config JSON files rewritten in place across six supported clients (Claude / Cursor / Zed / VS Code / Windsurf / Neovim), and --secret KEY=value flags piped through to the Machine's secrets. Canonical wiki instance of patterns/remote-mcp-server-via-platform-launcher. (Source: sources/2025-05-19-flyio-launching-mcp-servers-on-flyio.)

Together with flymcp (local stdio wrapper, 2025-04-10), flyctl now spans both axes of MCP-server ergonomics: wrap a local CLI as a local MCP server (patterns/wrap-cli-as-mcp-server, flymcp) and deploy a local MCP server as a remote MCP server (patterns/remote-mcp-server-via-platform-launcher, fly mcp launch). See systems/fly-mcp-launch for the subcommand's full option surface + concepts/mcp-client-config-fragmentation for the editorial motivation.

Seen in

Last updated · 200 distilled / 1,178 read