> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fly agent setup

> Set up Claude Code, Codex, Cursor, and other coding agents for Fly.io in one command. fly setup agent installs the Fly skills and the hosted Fly MCP server.

`fly setup agent` configures your coding agents to work with Fly.io. It installs the [Fly agent skills](https://docs.fly.io/model-context-protocol/agent-skills.md), 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.

> [!NOTE]
>
> `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](https://docs.fly.io/flyctl/install.md).

## Run the setup

```sh theme={null}
fly setup agent
```

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

```text theme={null}
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`](./agent-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](https://mcp.fly.io/guide.md) 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:

```sh theme={null}
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`:

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
fly setup agent --json -y --skip-login
```

```json theme={null}
{
  "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](https://docs.fly.io/model-context-protocol/agent-skills.md#other-ways-to-install).