All pages

Agents and MCP

There are two ways in, and the difference is what the agent can reach: a hosted server every host answers, and a local one that can also see the checkout the agent is working in.

Hosted, on every host

pilot login
pilot mcp install claude-code
pilot mcp install --list

pilot mcp install writes the server entry into that agent's own config file, in that agent's own shape, merged with whatever is already there. --list names the harnesses it knows, --project writes the repository-scoped file rather than the user-wide one, and --print shows the entry without writing anything.

Any client can also be pointed at the address by hand.

{
  "mcpServers": {
    "pilots": {
      "type": "http",
      "url": "https://api.pilotrun.app/mcp",
      "headers": { "Authorization": "Bearer $PILOT_API_KEY" }
    }
  }
}

The endpoint is Streamable HTTP and stateless, on every host of the fleet. There is no gateway and no session pinned to one machine, so a client that reconnects to a different host loses nothing. It carries everything that needs only the API: machines, exec, logs, metrics, checkpoints, forks, promotion, services, releases, rollback, domains, volumes, databases, grants, diagnosis, and the documentation itself.

Local, when the agent has a checkout

pilot mcp install claude-code --stdio

The same server as a local process, which adds the tools that need the agent's own filesystem: deploy, build, plan, generate_dockerfile, and pushing and pulling a file. Use this one when the agent is working in a repository. The hosted server says so too, so an agent that finds deploy missing is told where it is rather than guessing.

A client that dials the endpoint with no credential is refused with a pointer to the resource metadata, which names the dashboard as the authorization server. The client registers itself, opens a browser, and the person approves it on a consent screen. What comes back is an ordinary pilots token, so nothing on the fleet learns a second kind of credential and revoking it on the tokens page stops it everywhere.

The three restrictions on that token

Restriction	What it does
A name prefix	Every machine and service the token names must start with it.
A machine cap	How many machines with that prefix may exist at once, counted at create time.
An expiry	When the token stops authenticating, checked on every request.

The fleet enforces all three, and a refusal says which one was hit and what would work instead. A name outside the prefix comes back with the prefixed name spelled out.

The Claude Code plugin

/plugin marketplace add pilotsrun/pilots-claude-plugin
/plugin install pilots@pilots

It adds the hosted server, the pilots skill, two skills you invoke yourself, and a hook that asks before destroy_machine, restore and rollback, and before an exec that ought to be checkpointed first: a migration, a package upgrade, a recursive delete.

It uses the key pilot login stored. With no stored key, the browser login above is offered instead.
It does not read PILOT_API_KEY, because Claude Code hides the environment from a plugin. Headless, run pilot login --token <key>.
PILOT_API_URL points it at another fleet.
Cursor, Codex, Copilot and Kiro read the portable manifest in the same directory.

The plugin has its own page with the guard, the credential and the repository case in full.

In a repository, pilot init copies the skill in and registers the server, so an agent opening that checkout finds both.

pilot init

Claude Code inside a machine

Two different things, and only one of them needs anything. Driving a machine from outside is the normal case and needs no Anthropic credential anywhere: you are already signed in where you are, and create, exec and the file tools are your hands in the sandbox. An agent LIVING in the machine, working on its own with every permission because there is nothing of yours in there to wreck, has to be signed in, and a machine is a different computer.

pilot claude scratch

The first run sets the credential up once per computer. Every run after that, on any machine, opens Claude Code already signed in, and it installs Claude Code in the machine the first time.

Two practical notes. A machine with less than a gibibyte of memory is tight for Claude Code, and pilot machine resize fixes that. While it is running, its credential is in the machine's memory, so exit it before forking that machine for somebody else.

Editors

Two editors open a machine as a folder on the same address. The VS Code extension mounts it as a workspace folder and opens a shell in it. The Neovim plugin opens the same address, with a terminal command beside it.

Every read and write in both is a command over the exec route, so there is nothing to install in the guest and no port to open, and a write to a suspended machine wakes it.

The agents page has the case for all of this, and what a machine may do covers what an agent inside a machine is allowed to reach.