Skip to content
pilots
Dashboard
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"
  • cmd is a string, run by the shell, or an array, run as given. cwd, env and user mean what they mean for exec.
  • env is 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: true keeps 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-Offset and 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_found for a missing file, ?list=1&recursive=1&exclude=node_modules lists a tree, and /archive streams 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/tanstack and @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 api covers anything a client would.