Skip to content
Skip to content
PilotPods

Deploy

Run PilotPods on an always on Mac

Keep pods working while your laptop sleeps. Put an instance on a Mac that stays on. launchd keeps the services alive. doctor, backup and upgrade keep it healthy.

pilotpods
$
Everything stays on your Mac
Local
Background services per instance
5
Commands to keep it healthy
4
Supported engines
5

launchd services

Services that start themselves and stay up

PilotPods ships launchd templates for its background services. Each service is a small loop started by one command. launchd restarts it if it stops.

keepalive

Keeps the instance daemon running and records that it is alive.

blockedwatch

Watches for blocked tickets and opens an escalation.

decisions

Tracks decisions waiting on you so none get lost.

bushealth

Checks the message bus every 60 seconds and reports its state.

runner

Runs queued tasks through their stages on the engine each Pod COS or Pilot COS uses.

One label prefix per instance

Each instance has its own launchd label prefix, such as com.pilotpods.<name>, so two instances on one Mac never share a service.

Install the agents, then check them

install.sh checks for python3 and git, creates the ~/.pilotpods data directory and installs a launchd agent template. It is safe to re-run. You load the agents yourself, so nothing starts without you.

service run loops until STOP ALL is pressed. Add --once to run one pass and exit, which suits testing by hand.

Install and list services
$ ./install.sh$ ./pilotpods init --instance default$ ./pilotpods service list --instance default$ ./pilotpods service run bushealth --once

Heartbeats and leases

Know when something goes quiet

Each COS records a heartbeat on an interval. If it stops, the lease expires and a restart hook runs.

  1. 1

    Beat

    Each COS and service writes a heartbeat on its own interval.

  2. 2

    Lease

    Each COS has a lease threshold. Miss it and the lease expires.

  3. 3

    Escalate

    A stale heartbeat opens an escalation. So do blocked tickets, silent COSs, stuck tasks and a downed service.

  4. 4

    Restart

    The restart hook is pluggable. Wire it to your own process supervisor.

Read the heartbeats
$ ./pilotpods status --instance default$ ./pilotpods service list --instance default$ ./pilotpods checkin list --instance default

status prints a bus health summary: pods, COS heartbeats, open and overdue tickets. It ends in RESULT: HEALTHY or RESULT: UNHEALTHY.

Doctor

One command for a health check

doctor checks service and launchd state and that instances are isolated from each other. It ends in RESULT: OK or says what is wrong.

  • Service and launchd state for this instance
  • Cross instance isolation: data dirs, ports and prefixes do not overlap
  • Optional self test suite with a pass count
Health and isolation
$ ./pilotpods doctor --instance default$ ./pilotpods doctor --instance default --selftest$ ./pilotpods verify-isolation --instance default

The five com.pilotpods rows are listed for visibility. A row with no loaded agent does not count against the verdict.

Backups and restore

Back up before you change anything

A backup is one dated archive of the instance data directory. Restore shows what is inside first and applies it only when you pass --yes.

Writes the instance data directory to a dated .tar.gz in its backups folder. Use --out to pick another path.

Back up
$ ./pilotpods backup --instance default$ ./pilotpods backup --instance default --out ~/Backups/default.tar.gz

Upgrades

Upgrade in four calm steps

An update changes code, and sometimes the database. upgrade applies pending schema migrations to one instance.

  1. 1

    Back up

    Make a fresh archive first.

    Terminal
    $ ./pilotpods backup --instance default
  2. 2

    Pull the new code

    Update your clone.

    Terminal
    $ git pull
  3. 3

    Apply migrations

    Move the database to the current schema.

    Terminal
    $ ./pilotpods upgrade --instance default
  4. 4

    Check

    Confirm it is healthy.

    Terminal
    $ ./pilotpods doctor --instance default

On a current instance, upgrade reports the latest schema version and does nothing.

Honest status

What works today and what is next

FeatureStatusNotes
launchd agents from install.shWorks todayInstalls a launchd agent template for the default setup.
doctor, status, backup, restore, upgradeWorks todayAll wired into the CLI and checked.
instances start and stopWorks todayRun as a background daemon with a heartbeat, not a launchd agent.
One launchd plist per named instanceComing soonComing soon: install.sh will take --instance and render a plist for it.
Templates for all five service rowsComing soonComing soon: some rows have no loadable agent yet.

Questions

Running on a server, answered

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