Skip to content
Skip to content
PilotPods

Docs

PilotPods documentation

Learn the model, follow a guide, look up a command. Everything here describes what PilotPods does today, and anything planned is marked Coming soon.

Start here

Find your way around

Three shelves: concepts to understand the model, guides to get things done, reference to look things up.

Get started

From a blank Mac to your first task, with every command to copy.

Open guide

How pods are created

The Pilot COS, Pod COSs, workers and engines, and who decides what.

Read concept

Commands

Every CLI command and flag, taken from pilotpods --help.

Open reference

Multiple instances

Run isolated instances side by side with their own data, ports and Keychain prefix.

Read concept

Console

The localhost web console: pods, approvals, spend and the STOP ALL control.

See console

Security

Local only, no telemetry, and a command that proves it.

Read more

Run on a server

Keep an instance running on an always on Mac.

Read guide

FAQ

Short answers to the questions people ask first.

Open FAQ

Concepts

The glossary

Eleven terms cover the whole model. Filter by the layer you are interested in.

Instance

Structure

One full, isolated PilotPods deployment with its own data directory, database, message bus, ports, launchd label prefix and Keychain prefix. One Mac can run many.

$ pilotpods init --instance research

Pilot COS

Structure

The chief of staff you talk to. It turns your goals into work and hands it to the right pod.

$ pilotpods status

Pod

Structure

A named team inside an instance, such as a Research pod, led by a Pod COS.

$ pilotpods pod create research

Pod COS

Structure

The lead of a pod. It manages its members and checks their work. It does not build.

$ pilotpods hire planner --pod POD_ID

Worker

Structure

A pod member that does one kind of work, running on an engine.

$ pilotpods hire writer --role writer

Engine

Structure

The agent runtime a member uses. Five adapters ship: claude, codex, antigravity, gemini, and grokbot, which is monitor only.

$ pilotpods engines list

Approval and cap

Control

Spend is recorded against a daily cap per instance. A record that would exceed the cap is refused unless a human overrides it.

$ pilotpods spend record 1.00

STOP ALL

Control

The kill switch. It ends every live session and stops the daemon for one instance.

$ pilotpods stop --all

Check-in

Data

A timestamped status line a member appends to the board. It is never edited, only added to.

$ pilotpods checkin add --cos-id COS_ID --status "on track"

Audit log

Data

An append-only record of wake, terminate, approval and spend events for an instance.

$ pilotpods audit list

Backup

Data

A dated .tar.gz of one instance's data directory with a manifest. Restore previews first and needs --yes to apply.

$ pilotpods backup

Every command, every flag

The glossary shows one command per term. The Commands page lists them all, taken from pilotpods --help.

Open commands

Guides

Do the common things

Each guide is a short run of real commands. Copy them as they are and change the names.

Create an instance and open the console

init creates or re-opens a named instance. doctor checks the services, and ui serves the console on 127.0.0.1 only.

  1. 1init --mission "Weekly market notes"
  2. 2demo
  3. 3doctor
  4. 4ui --open
first-run.sh
$ ./pilotpods init --instance research --mission "Weekly market notes"$ ./pilotpods demo --instance research$ ./pilotpods doctor --instance research$ ./pilotpods ui --instance research --open

Reference

Commands at a glance

The commands you will use most. The full list with every flag is on the Commands page.

  • $ pilotpods initSetup

    Create or re-open a named instance

  • $ pilotpods instances start | stop | status | listSetup

    Run and inspect instances

  • $ pilotpods ui --openConsole

    Serve the web console on 127.0.0.1

  • $ pilotpods pod create | list | stopPods

    Manage pods in one instance

  • $ pilotpods hire NAMEPods

    Add a member, optionally matched to a job description

  • $ pilotpods engines list | detectEngines

    Show the five engines and detect installs

  • $ pilotpods spend record AMOUNTControl

    Record spend against the daily cap

  • $ pilotpods stop --allControl

    Kill switch for one instance

  • $ pilotpods audit listData

    Append-only event log

  • $ pilotpods backup | backup-list | restoreData

    Archive and restore instance data

  • $ pilotpods doctor | status | upgradeHealth

    Health, bus summary and schema migrations

  • $ pilotpods verify-isolationHealth

    Check for no outbound calls, no tracking and no writes outside the data dir

Open full command reference

Docs FAQ

Quick answers

Run your first pod in minutes

Install on a Mac, create an instance, and open the console. Everything stays on your machine.

Get started Read the docs
  • MIT licence
  • No telemetry
  • CLI and console
Quick start
$ ./install.sh$ ./pilotpods init --instance default$ ./pilotpods ui --open