Get started
From a blank Mac to your first task
Eight short steps, all on your own Mac. Nothing leaves your Mac, and every command below is a real PilotPods command you can copy.
$
Before you start
What you need
PilotPods runs locally. The installer checks the basics for you and is safe to run again.
A Mac
PilotPods runs as launchd services on macOS, with data kept under ~/.pilotpods.
python3 and git
install.sh checks for both and tells you in one line if either is missing.
An engine you already use
Claude, Codex, Antigravity or Gemini. The console detects what is installed. Grok bot is monitor only.
No account, no tracking
No sign up. verify-isolation proves zero outbound network calls and no tracking code.
The path
Eight steps, in order
Each step shows the command and what you should see. Use the copy button, then paste it into Terminal.
- 1
Install
Clone the repo and run the installer. It checks for python3 and git, creates the ~/.pilotpods data directory and installs a launchd agent template without loading it.
Safe to re-run any time.
Terminal$ git clone <this-repo-url>$ cd pilotpods$ ./install.sh - 2
Create an instance
Everything lives in a named instance. Each has its own data directory, database, ports, and launchd and Keychain prefix. Nothing works until one exists.
Skip it and status says: No PilotPods instance 'default' is registered yet.
Terminal$ ./pilotpods init --instance default - 3
Seed demo data
Demo adds a few clearly labelled fake pods, members and tickets so your first run has something to show.
Add --force to reseed if demo data already exists.
Terminal$ ./pilotpods demo --instance default - 4
Check status
A bus health summary for the instance: pods, COS heartbeats, open and overdue tickets.
It ends in RESULT: HEALTHY or RESULT: UNHEALTHY.
Terminal$ ./pilotpods status --instance defaultRESULT: HEALTHY - 5
Run doctor
Checks service and launchd state and cross-instance isolation. Add --selftest to run the built-in self-test suite and get a pass count.
It ends in RESULT: OK or tells you what is wrong.
Terminal$ ./pilotpods doctor --instance default$ ./pilotpods doctor --instance default --selftest - 6
Open the console
Serves the web console and its API on 127.0.0.1 only. --open opens your default browser. --port picks another port.
Local only. Stop it with Ctrl-C.
Terminal$ ./pilotpods ui --open - 7
Name your Pilot COS
On first open the console walks you through onboarding. It detects your engines, then asks you to name your Pilot COS and set a one line mission. You can change both later in settings.
Any name works. Skipper is an example.
Console onboardingPilot name SkipperMission Keep project-a moving - 8
Send your first task
Tell the Pilot COS what you want done. It plans the work with your engine, creates a pod with a mission and tickets, and posts a summary back to the task thread. Risky steps wait for your approval.
Watch it live on the console. STOP ALL is always one click away.
Console task threadTask Research three options for a project-a landing page-> plan -> pod + tickets -> reply in the thread
What you just built
One Pilot COS, pods that do the work
Your Pilot COS plans and delegates. Each pod has its own Pod COS and workers running on your engines. You stay in the loop for approvals, budgets and the kill switch.
- Pilot COS: the one you named. It turns a task into a plan.
- Pods: created per task, each with a mission and tickets.
- Heartbeats show who is alive. Approvals and daily spend caps stay with you.
- ./pilotpods stop --all stops every daemon and session for the instance.
Keep going
Everyday commands
All accept --instance NAME. Every subcommand has its own --help, which is the source of truth.
If something looks off
Quick fixes
Run your first pod in minutes
Install on a Mac, create an instance, and open the console. Everything stays on your machine.
- MIT licence
- No telemetry
- CLI and console
$ ./install.sh$ ./pilotpods init --instance default$ ./pilotpods ui --open