ppilot command reference

ppilot is the scalable Run-production CLI. It exposes exactly two commands:

ppilot
├── run       execute plan() / execute(item) with durable recovery
└── produce   create independent pVisor Runs from a streaming planner

Dataset discovery, SQL, built-in analysis, find, import/export, and serving are owned by pchronicle.

run

ppilot run plan.py --workers 8 --per-worker 2 --sink ./results
ppilot run plan.py --workers 8 --sink ./results --resume
ppilot run plan.py --check

The script defines plan() and execute(item). pPilot applies bounded concurrency and backpressure, writes terminal results to the durable sink, and uses stable task identity for resume and retry. --check validates the plan and a sample execution without running the full workload.

produce

ppilot produce production.py --output ./runs --parallelism 8
ppilot produce production.py --output ./runs --parallelism 8 \
  --cluster-network-limit 10mbps -- --dataset train

The planner's plan() may be a synchronous or asynchronous iterator. Each item describes one Run:

def plan():
    for index in range(100):
        yield {
            "id": f"task-{index:04d}",
            "agent": "codex",
            "command": ["codex", "exec", f"Solve task {index}"],
            "cwd": "/work/eval",
        }

Each emitted item gets its own pVisor workspace below --output. The planner is streamed under the concurrency window, so large batches are not fully held in memory. The command writes production-report.json; any failed Run makes the command exit unsuccessfully after the report is durable.

--cluster-network-limit divides a conservative aggregate proxy rate across the requested parallelism. It requires Gateway capture and does not cover direct sockets that bypass the explicit proxy.

Runtime ownership

Both commands start an in-process, job-scoped Supervisor. pPilot owns planning, leases, retries, reconciliation, and collection. pVisor owns Run execution and the embedded Gateway. pChronicle owns trajectory Dataset operations.

The executable's --help is authoritative for flags and defaults.