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 setup
pilot mcp install claude-code
pilot mcp install --list
pilot setup is the one command: it finds the agents installed on
the computer, puts the Pilots skill and the server entry into each, and checks that you
are signed in. Run it again later and it reports nothing changed.
pilot mcp install does one agent at a time, writing 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.
The entry it writes carries the address and no key. The agent signs in
through the browser the first time it connects and comes back with a token of its own,
held to what you approved on the consent screen, so no copy of your own key sits in an
agent's config file. That is the default for Claude Code, Codex, Cursor, OpenCode, Gemini
CLI, Zed, GitHub Copilot CLI, Factory Droid, Antigravity and Pi. VS Code and Windsurf
cannot sign in that way, so their entries carry the key pilot login stored,
and --key writes that form for any harness.
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, detached processes, files, logs, metrics, checkpoints, forks, promotion, services, releases, rollback, domains, volumes, databases, grants, diagnosis, and the documentation itself.
The process tools are the ones an agent driving a long job reaches for:
process_start leaves a command running under a name, process_output
reads its output from a byte offset so nothing is read twice or missed, and
process_status says how it ended. The file tools, file_read,
file_write, file_list and file_remove, move bytes
without a shell in between. process_start takes no environment on purpose: a
secret there would pass through the model, so it reaches a process from
pilot process start --env, which you run yourself.
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, add_database, 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 with no token
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 two restrictions on that token
The consent screen asks what the token can reach, and the narrow answer is the one already chosen: only what it creates.
| Restriction | What it does |
|---|---|
| A name prefix | The token can act on and look inside only the machines, services, volumes and templates whose names start with it, and everything it creates is named under it. The rest of the team it can see exists, and in what state, and nothing more: no files, no processes, no logs. A service's replicas count as inside the prefix when the service's name is. |
| An expiry | When the token stops authenticating, checked on every request. |
The fleet enforces both on every route, and a refusal is
scope_required naming the prefix and the name that reached past it, never a
not_found. A token can also ask for read alone: it can watch
everything in the team, logs included, and change nothing. It cannot run commands or
read files. GET /v1/whoami answers a token's own prefix and expiry, so an
agent can read its grant before it is refused.
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 loginstored. 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, runpilot login --token <key>. PILOT_API_URLpoints 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
An agent run you start yourself, rather than an interactive session, is a
process: pilot process start <machine> run --keep-awake --env with the
credential, then pilot process output <machine> run --follow from anywhere,
as often as you like, because the output is kept on the machine and addressed by offset.
--keep-awake keeps the machine from sleeping under it.
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.