Lease lifecycle

TL;DR

• This page is the operational walkthrough for driving a lease by hand: open it, stamp resources at create time, wait for the deployment, promote what you keep, and close with commit (keep everything) or rollback (discard everything).
• The verb surface is lease create → file link --lease → lease wait → lease promote → lease commit / lease rollback, plus the operational helpers wait, debug, set-result, collect-outputs, list, delete, and delete-bulk.
• For the common case — running a live test from a manifest — ppl lease run --test=<manifest> drives the whole lifecycle for you. The verbs below are the lower-level surface for runs that the manifest grammar does not cover.
• For the ownership model, verb semantics, and TTL philosophy behind these commands, see Leases.

The default consumer: lease run

Use this mode when you have a live-test manifest and you just want it to run.

ppl lease run --test=<manifest> --runtime=<id> drives the entire lifecycle for a manifest-described live test, so the common consumer does not touch the verbs directly. It mints the lease, publishes the candidate component prerelease stamped with the lease, uploads every local fixture stamped with the lease, opens the live-test WebSocket, streams build and deploy events as NDJSON, and auto-rolls-back the lease at the end. The exit code is 0 on a ready test and 1 on a failed one, which is what a CI step needs.

Passing --keep-lease skips the auto-rollback so you can inspect the live environment before deciding to commit or rollback by hand. Reach for it during exploratory work; leave it off in CI, where the run should clean up after itself.

See Test with a live backend for the manifest schema and the full event stream contract.

Open a lease

Use this when the run is custom enough that the manifest-driven shortcut does not fit.

Opening a lease declares the runtime the deployment will eventually run on, the maximum unattended lifetime, and an optional label that makes the lease easy to find later. The lease starts in state open and accepts stamped Creates immediately:

ppl lease create --runtime <runtime_id> --ttl 30m --label q-faiss-liveCopy

Labelling is worth doing. A lease labelled nightly_vector_index is findable later by substring search, is bulk-rolled-back by label prefix, and identifies what a stuck lease was doing. Unlabelled leases work the same way; they are just harder to recognize during housekeeping.

Pick the TTL so it comfortably covers the longest expected run; the platform applies a default and caps over-long values. A TTL shorter than the run produces a false rollback while the test is still going. --runtime falls back to the configured default_runtime when omitted, and --cleanup-policy defaults to delete_ephemeral_resources — pass retain_all to keep owned resources in place when the lease closes.

Stamp resources at Create time

Use this whenever the resource should die with the lease.

The one command that exposes a standalone --lease flag is ppl file link:

ppl file link <source_uri> --lease <lease_id> --kind <source_kind> --type <file_type>Copy

Backends, deployments, versions, and components are stamped inside ppl lease run automatically — no hand-typed flag. For the stamp-at-create rule and why there is no way to move an existing row into a lease later, see Leases.

Wait for the deployment to come up

Use this to gate "the run is ready" on the actual runtime, not on a sleep.

A lease holds a deployment; the deployment holds containers; containers take some non-zero time to start. ppl lease wait is the gate: it opens a server-sent-events stream, writes one NDJSON event per line, and exits 0 when the lease reaches its target state (deployed by default), 1 on failed, timeout, or transport error.

ppl lease wait <lease_id> --until started --max-crashes 5 --timeout 15mCopy

--until lets you choose how strict "ready" means. started exits as soon as the deployment is running, stable (the default) waits for every container to be running without crash budget left. --max-crashes sets the per-container restart budget and --timeout is the whole-call wall-clock cap. The exit code is what you pipe into the next CI step.

Promote, then commit (or rollback)

Use Promote when one specific row of the lease should survive even if the rest is discarded.

For what each verb means against the ownership model, see Leases. Operationally the sequence is:

ppl lease promote <lease_id> --kind file --id <file_id>Copy
ppl lease commit <lease_id>      # keep everything still in the lease, close itCopy
ppl lease rollback <lease_id>    # discard everything still in the lease, close itCopy

The typical pattern is: a live test runs, produces one generated artifact worth keeping (say a built FAISS index), Promotes that single file out of the lease, then rolls back the rest. The kept file survives; the candidate component prerelease, the test backend, the temporary fixtures, the deployment all get cleaned up.

Commit and rollback are idempotent on already-closed leases. Calling either on a closed lease is a no-op success — useful for cleanup scripts that do not want to special-case the rare race with a TTL auto-rollback.

Bulk housekeeping

Use this when many leases need to die at once.

Bulk rollback closes many leases in one call — for example, every failed lease from a CI run. The filters compose with AND, and the server refuses an empty filter body so a typo cannot roll back every lease in the workspace.

ppl lease rollback --bulk --older-than 24hCopy
ppl lease rollback --bulk --failedCopy
ppl lease rollback --bulk --runtime <runtime_id> --label-prefix nightly-Copy

The nightly cleanup pattern is one line of cron — and because every lease either committed (kept its rows) or rolled-back (destroyed them), there is no residual state to chase.

Bulk rollback closes still-open leases. To purge the rows of leases that are already closed, ppl lease delete-bulk takes the same filter shape plus --status (limited to the closed states rolled_back, failed, committed) and a --dry-run preview, and never touches an open lease.

ppl lease delete-bulk --closed-before 24hCopy
ppl lease delete-bulk --status rolled_back --older-than 7d --dry-runCopy

Debug a failed lease

Use this first when something went wrong.

ppl lease debug <lease_id> returns one JSON bundle: the lease, its backend, the deployment's status and message, and a per-container status / exit code / status message. It is the single call to make first when a lease fails — it almost always says enough to decide whether the next step is "read container logs", "fix the backend graph and retry", or "the runtime is wedged".

Pairing it with ppl lease set-result <lease_id> --status failed --json '{…}' preserves a structured result and the debug bundle past the close, which is what makes post-mortem possible after the lease itself is gone.

Where this fits

This page is the command sequence for driving a lease by hand; the ownership model, verb semantics, and TTL philosophy that make the surface coherent live in Leases. The operational helpers — wait, debug, set-result, collect-outputs, list, delete, delete-bulk — are documented in the sections above.

Related

• Test with a live backend — the canonical lease consumer.
• Leases — the ownership model behind these commands.
• Deploy and monitor — non-ephemeral production deploys.
• Runtimes and nodes — where the deployment runs.
• Prove behavior — leases as the isolation boundary for proof loops.