Fly agent setup

fly setup agent configures your coding agents to work with Fly.io. It installs the Fly agent skills, adds the hosted Fly MCP server at https://mcp.fly.io to supported agents it detects, and offers to sign you in to Fly.io.

fly setup agent is available in flyctl releases after v0.5.1. If your fly does not have the command, run fly version upgrade or install flyctl.

Run the setup

fly setup agent

The command lists what it is about to do for each agent and asks once before writing anything:

Fly Agent Setup

This will set up 3 agent(s):

  Universal (.agents)
    skills  /Users/you/.agents/skills
    MCP     skipped (no MCP configuration for this agent)

  Claude Code
    skills  /Users/you/.claude/skills
    MCP     /Users/you/.claude.json

  Cursor
    skills  /Users/you/.cursor/skills
    MCP     /Users/you/.cursor/mcp.json

? Set up 3 agent(s)? Yes

It installs the skills first, reporting each one, then prints a summary line per agent and reminds you to restart your agents. If you are not signed in to Fly.io, it offers fly auth login and fly auth signup, or lets you skip for now. Running the command again is safe. Individual skills that are already current are reported as “already up to date.” The per-agent summary and JSON skills field still report installed. An unchanged MCP entry reports already_configured. Restart your coding agents after the setup. Most agents read their skills directory and MCP configuration at startup.

What it sets up

Skills. The skills go into ~/.agents/skills and into the global skills directory of every detected agent, exactly as fly skills install does. Files you have edited are left alone and reported. Use fly skills afterwards to check, update, pin, or remove them. MCP server. Each agent that has a global MCP configuration gets an entry named fly that points at https://mcp.fly.io. The entry stores only the URL. No access tokens, client IDs, or secrets are written to disk.

Agent	MCP configuration
Claude Code	`~/.claude.json`
OpenAI Codex	`~/.codex/config.toml`
Cursor	`~/.cursor/mcp.json`
OpenCode	`~/.config/opencode/opencode.json` or `opencode.jsonc`
GitHub Copilot	`~/.copilot/mcp-config.json`
Factory Droid	`~/.factory/mcp.json`
Antigravity	`~/.gemini/config/mcp_config.json`
Pi	Skills only
Universal (`~/.agents/skills`)	Skills only

An agent is detected when its parent directory exists, for example ~/.claude. CODEX_HOME, CLAUDE_CONFIG_DIR, and COPILOT_HOME are honored when set, and OpenCode uses $XDG_CONFIG_HOME/opencode when that variable is set. The command prints the resolved path for each agent. While the command does install MCP configuration, it does not install the Claude Code plugin’s confirmation hook for destructive or billable operations. You should review the permissions for any destructive tools or tools which create billable resources. Sign-in. The command installs the skills and configures the MCP server before checking whether you’re signed in to Fly.io. If you skip or cancel sign-in, your agent configuration stays in place. When an agent first connects to the Fly MCP server, a browser opens for OAuth authorization. You choose which organizations, apps, and products the agent can access. See the Fly MCP guide for more about the server.

Existing configuration

The command preserves existing MCP configuration unless it recognizes a fly entry it can manage. An entry counts as already configured if it has the expected type, points to https://mcp.fly.io, and isn’t disabled. Any extra settings you’ve added, such as headers, are preserved. Anything else is reported as a conflict and left unchanged, for example an entry that points at a different URL. Pass --force to repair the keys the command owns while keeping your extra keys:

fly setup agent --force

A configuration file that cannot be parsed is left untouched. That agent’s MCP step is reported as failed with the parse error, and the other agents are still set up. A fly entry that runs a local command instead of pointing at a URL is never overwritten, even with --force. Remove it yourself first. If a configuration file is a symbolic link, the command updates the file it points to, as long as that file stays inside the agent’s configuration directory or your home directory. A link that points anywhere else is left untouched.

Choose agents and steps

Name agents with --agent to set up only those. Use the same slugs as fly skills, and include universal to keep ~/.agents/skills:

fly setup agent --agent universal,claude-code,codex

Skip a step you do not want:

Flag	Effect
`--skip-skills`	Configure the MCP server without installing skills.
`--skip-mcp`	Install skills without touching MCP configuration.
`--skip-login`	Skip the sign-in check and browser login.

--force here only repairs MCP entries. To overwrite skill files you have edited, run fly skills install --force.

Scripts and CI

Pass --yes (or -y) to skip the setup confirmation. In an interactive terminal, if you are not signed in, it also starts fly auth login and opens a browser without asking. Add --skip-login to prevent this, including when using --json. When standard input is not a terminal, the command does not prompt or open a browser to sign in. It still writes the skills and configuration, and it tells you to run fly auth login when you are ready. An installer or setup script can run the command in embedded mode, which prints one line per agent and nothing else on standard output:

FLY_SETUP_EMBEDDED=1 fly setup agent -y

Pass --json to get the same summary as JSON. Each agent reports its skills and mcp status with a human-readable mcp_detail, and the auth object says whether you are signed in or skipped sign-in:

fly setup agent --json -y --skip-login

{
  "ok": true,
  "agents": [
    {
      "slug": "claude-code",
      "name": "Claude Code",
      "skills_dir": "/Users/you/.claude/skills",
      "skills": "installed",
      "mcp": "configured",
      "mcp_path": "/Users/you/.claude.json",
      "mcp_detail": "configured (/Users/you/.claude.json)"
    }
  ],
  "auth": { "ok": false, "skipped": true },
  "restart_hint": "Restart your coding agent(s) to load them.",
  "authorize_hint": "The first MCP call opens a browser to authorize https://mcp.fly.io."
}

The skills status is installed, preserved_local_changes, incomplete, failed, or skipped. The mcp status is configured, already_configured, conflict, failed, or skipped. The command exits non-zero when skills fail or are left incomplete for one or more agents. Locally deleted skill files are preserved as deletions and leave the installation incomplete. It also exits non-zero when MCP setup fails for an explicitly named agent or when no agent has successfully installed skills or configured MCP. If you have previously configured MCP entries, those will count as success. A conflict does not count as a failed MCP step. A failed sign-in does not change the exit status.

Undo

fly skills remove deletes the installed skills. There is no command to remove the MCP entry; delete the fly entry from the configuration file listed above for each agent.

Permissions

The skill asks the agent to confirm before destructive or billable operations and the Fly MCP server enforces the grant you approve in the browser. Beyond that, your agent’s own permission prompts apply. For the plugin confirmation hook’s coverage and Python requirements, see Other ways to install.

​Run the setup

​What it sets up

​Existing configuration

​Choose agents and steps

​Scripts and CI

​Undo

​Permissions

Run the setup

What it sets up

Existing configuration

Choose agents and steps

Scripts and CI

Undo

Permissions