Concepts
Run isolated instances side by side
Each instance has its own data directory, database, port range and budget, so work for one project never touches another. Start, stop and remove them by name, then prove the walls hold.
One Mac
no shared state between instances- own SQLite database
- own port range
- own budget cap
- own SQLite database
- own port range
- own budget cap
- own SQLite database
- own port range
- own budget cap
What is isolated
Eight things every instance owns
These are set when you run init and kept for the life of the instance. Nothing is shared except two small bookkeeping files.
Data directory
Default ~/.pilotpods/<name>, or any path you pass with --data-dir. Plan file, pod file, check-in board and logs live here.
SQLite database
One database file per instance, inside its own data directory. No shared file two instances could collide on.
Message bus
A bus namespace under the data directory. The messages table lives in the instance's own database.
Port block
A fixed block of 20 TCP ports on 127.0.0.1, starting at 8700, recorded centrally so no two instances share one.
launchd labels
Every agent is labelled com.pilotpods.<name>.*, so stopping one instance never touches another.
Keychain prefix
Engine credentials are read from pilotpods-<name>-* items. Files hold pointers, never values.
Daily budget
A per-instance daily cap, plus a machine-wide cap across all instances. Warns at 80 percent of the cap.
Session limit
A cap on concurrent engine sessions inside the instance, stored in the guard file.
Walkthrough
From zero to two instances in five commands
Run these from the PilotPods folder. Instance names use letters, digits, dash and underscore, up to 32 characters.
- 1
Create an instance
init registers the name, picks a port block and creates the data directory. Add --data-dir to put it somewhere else.
Terminal$ ./pilotpods init --instance project-a$ ./pilotpods init --instance project-b --data-dir ~/Work/project-b-pods - 2
List and inspect
See every registered instance, then read back the data dir, port range, launchd prefix and Keychain prefix of one.
Terminal$ ./pilotpods instances list$ ./pilotpods instances status --instance project-a$ ./pilotpods instances status --all - 3
Pick the active one
use sets the default for later commands in this shell, so you can leave off --instance. Passing --instance always wins.
Terminal$ ./pilotpods instances use project-a$ ./pilotpods status - 4
Start and stop by name
start launches that instance's daemon, stop touches only its own launchd agents. start refuses when the concurrency cap is reached.
Terminal$ ./pilotpods instances start --instance project-a$ ./pilotpods instances stop --instance project-a - 5
Remove when done
remove asks you to type the name before it deletes data. Use --keep-data to unregister only.
Terminal$ ./pilotpods instances remove --instance project-b --keep-data
Live, representative output
$
Budgets and limits
Caps that stop runaway work
Limits live in one machine-wide guard file, ~/.pilotpods/guard.json. It stores paths, ports, prefixes and spend numbers, never a credential. Writes happen under a file lock so two commands cannot hand out the same port.
Running instances at once
Concurrency cap. start refuses past it.
Daily spend per instance
Small cost units your billing code assigns per engine call.
Daily spend across the machine
Shared total over all instances.
Warning threshold
A warning shows once spend crosses this share of a cap.
Concurrent sessions per instance
One engine wake for one COS counts as one session.
Ports per instance
Blocks start at 8700, never overlap.
How port blocks are laid out
Each block is 20 ports on 127.0.0.1. Blocks never overlap.
8700-87198720-87398740-8759These are the defaults. The numbers are plain cost units; PilotPods never converts them to money.
Proof
Check the walls, do not trust them
verify-isolation runs a real command cycle for one instance and reports a PASS or FAIL for each of three checks. Run it before any sensitive work goes near a private instance.
[a]No outbound network
The real CLI runs with socket connect and name lookups blocked and recorded. Any attempt fails the check.
[b]No telemetry code
Every source file in the repo is scanned for network client and telemetry shaped code, not just the files the cycle touched.
[c]Writes stay inside
Every file written during the cycle must land in the instance's data directory. Only guard.json and the current-instance marker are shared by design.
$ ./pilotpods verify-isolation --instance project-a[b] PASS - no telemetry or outbound network-client code path found[a] PASS - zero outbound network attempts during the command cycle[c] PASS - every write stayed inside the data dirRESULT: PASSThen check by hand
$ launchctl list | grep com.pilotpods.project-a$ find ~/.pilotpods/project-a -type lThe first should list only this instance's agents. The second should find no symlinks into another instance.
Reference
Every instances command
All of them take --instance NAME. Without it they use the instance chosen by instances use, else default.
instances listShow every registered instance with data dir, prefix and ports.
instances status [--all]Show one instance in detail, or all of them with their spend.
instances startStart the instance daemon. Refuses if the concurrency cap is reached.
instances stopStop that instance's daemon and launchd agents only.
instances remove [--keep-data] [--yes]Unregister. Deletes data after a typed name confirmation unless --keep-data.
instances useMake this the default instance for later commands.
verify-isolationRun the three isolation checks and print RESULT: PASS or FAIL.
Questions
Good to know
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