All pages
API and SDKs
Every host serves the whole API. There is no control plane in front of it and no host that has to be alive for a call to work, which is why a request about your machine is answered by a host that has never run it.
Calling it
curl -H "Authorization: Bearer $PILOT_API_KEY" \
https://api.pilotrun.app/v1/machines
A key goes in an Authorization header as a bearer token.
pilot login mints one for your laptop, and the dashboard's tokens page mints
the rest. To make a call with the key the CLI already holds, let the CLI make it.
pilot api /v1/machines
pilot api /v1/services --json
Keys and scopes
Four scopes, nested: each one contains the one before it. An unrecognised scope name fails closed rather than being treated as harmless, and a route that is not in the table below needs the highest scope.
| Scope | Reaches |
|---|---|
read
|
Watching, and nothing else: what exists and what state it is in, across
everything a deploy key can list, plus metrics, usage, releases, console
and build logs, who you are, and the MCP endpoint. It cannot change anything and
cannot look inside a machine, so no exec, no files, no process output and no
secret values. The key for watching a team.
|
machines
| Everything above, plus machines, checkpoints, volumes, plans and your outbound addresses, inside and out. |
deploy
| Everything above, plus services, builds, builders, domains and the repository connections a deploy reads. |
admin
| Everything above, plus the fleet's own inventory, minting keys, and any route not otherwise listed. |
A key can also be narrowed further when it is minted, with a name prefix
and an expiry, and GET /v1/whoami answers both back as name_prefix
and expires_at beside the key's organization and scopes, so a client can
read what it was granted before it is refused. An MCP client that arrives with no key at
all is walked into the browser and comes back with one
(agents and MCP).
The shape of an answer
Every non-success body has the same fields: a sentence for a person, a
code to branch on, a next naming the one thing to do about it,
typed details where there are any, and a request_id. Branch on the
code, never on the wording. The errors page is the whole
list.
Every answer, success or not, carries its X-Request-Id header,
the name the host that answered logged the request under. Quote it when you report
something: it is what matches one call to one line in a host's journal.
The routes you will use
| Route | What it is |
|---|---|
/v1/machines
| Create, list, inspect, relabel, exec, suspend, destroy. |
/v1/machines/{id}/processes
| Start, inspect, follow, signal and remove detached processes. |
/v1/machines/{id}/files
| Read, write, list and delete files as raw bytes. |
/v1/machines/{id}/archive
| A directory as a streamed tar. |
/v1/checkpoints
| Capture and restore. |
/v1/plan
| What a directory would deploy as, without building it. |
/v1/builds
| Build an image from a directory or a Dockerfile. |
/v1/services
| Services, releases, rollbacks and knobs. |
/v1/volumes
| Volumes and their snapshots. |
/v1/domains
| Custom hostnames and their verification state. |
/v1/metrics
| Your organization’s machines, as Prometheus text. |
/v1/usage
| What your organization used and what it cost, by month, machine or label, from one host or the whole fleet (billing and usage). |
/v1/pricing
| The price list and the monthly free allowance. Needs no key. |
/v1/health
| A host’s own view of itself, including whether it has caught up. |
/mcp
| The MCP endpoint (agents and MCP). |
Processes and files
A process started through the API is an exec that outlives its connection.
It has a name, a state (running, restarting, exited,
failed, stopped), an exit code or the signal that ended it, and a
restart policy (never, on-failure, always). Its stdout
and stderr are kept on the machine's disk and addressed by byte offset, so a reader that
lost its connection, or restarted, asks again with the offset it reached and gets the next
byte, never a duplicate and never a gap it is not told about.
# start a detached process; the answer carries where its output begins
curl -X POST -H "Authorization: Bearer $PILOT_API_KEY" \
"https://api.pilotrun.app/v1/machines/$MACHINE/processes" \
-d '{"name":"build","cmd":["npm","run","build"],"cwd":"app","keep_awake":true}'
# follow its output from byte 0 until it exits
curl -N -H "Authorization: Bearer $PILOT_API_KEY" \
"https://api.pilotrun.app/v1/machines/$MACHINE/processes/build/output?offset=0&follow=1"
# files are raw bytes
curl -T ./seed.sql -H "Authorization: Bearer $PILOT_API_KEY" \
"https://api.pilotrun.app/v1/machines/$MACHINE/files?path=/tmp/seed.sql"
cmdis a string, run by the shell, or an array, run as given.cwd,envandusermean what they mean for exec.envis held in the process's memory and nowhere else: never logged, never on the machine's disk. That is also why a process started with one is not restarted after a cold boot, which loses memory.keep_awake: truekeeps the machine from sleeping while the process runs. Without it a running process does not count, which is right for a dev server and wrong for an agent run.- The output answer says where its body begins in
X-Pilot-Output-Offsetand ends with trailers carrying the next offset and, once the process has finished, how it ended. A follow that is cut short ends without them, and a client resumes from its offset. - A file path is absolute or relative to the user's home. A write is atomic and
creates missing directories, a read answers
not_foundfor a missing file,?list=1&recursive=1&exclude=node_moduleslists a tree, and/archivestreams one as a tar.
Sandboxes has the same surface from the CLI,
and the SDKs wrap it as machines.processes and machines.files.
The typed clients
There are four, in JavaScript, Python, Go and Elixir. They speak the same API with the same names, each in its own spelling, and three of them carry a test that parses the daemon's own source so a field cannot be dropped from a client without the test failing.
Inside a machine, a client constructed with no key works: the SDKs read the token file the guest agent keeps fresh (what a machine may do).
npm i @pilots/sdk
go get github.com/pilotsrun/pilots/sdks/go
- The JavaScript client carries no runtime dependencies, and it also ships
@pilots/sdk/tanstackand@pilots/sdk/next(deploy). - The Python and Elixir clients are not published yet. Until they are, the HTTP API
and the CLI are the surfaces to reach for in those two languages, and
pilot apicovers anything a client would.