Concepts
Cleanup you can trust
Removing a box sounds simple. Doing it without ever deleting the wrong thing, or claiming a box is gone when it isn't, takes a few careful rules.
After every run#
When a run ends, PyBox removes its box and then looks again to confirm it's really gone. Only then does the receipt say REMOVED. If the engine can't be reached, PyBox doesn't assume success; it says UNCONFIRMED.
Every box is labelled#
Before creating a box, PyBox gives it three labels: who owns it (your installation), which run it belongs to, and when it expires (two minutes later). Before deleting anything, PyBox checks the box's full ID, its name and all three labels. There's no "delete everything that looks like PyBox".
Tidying up after a crash#
If PyBox is killed mid-run, the timer stops the program, but the empty, stopped box stays. The next time PyBox runs, it reconciles first:
- It lists only this installation's boxes. Containers that belong to anything else are invisible to it.
- It keeps anything that hasn't expired yet. A box from a run that might still be going is left alone.
- It removes an expired box only if it's stopped and every label still matches. It never force-kills a running box during cleanup.
- It confirms each removal by looking again.
You can also run reconciliation on its own:
$ pybox cleanupIf you never run PyBox again, a stopped box can stay indefinitely. Nothing deletes it in the background. That's a deliberate trade: no daemon, no background process with the power to delete things.
The note written before building#
Just before creating a box, PyBox writes a small private note (in ~/.pybox/runtime/attempts/) saying which box it's about to create. Once the box exists, it adds the box's ID. The note is deleted only after the box is confirmed gone.
The note solves a subtle problem. Suppose PyBox asks the engine to create a box, and the request times out. A moment later PyBox looks and finds nothing. Was it never created, or is it still being created? An empty list can't tell those apart. So PyBox keeps the note, reports the run as UNCONFIRMED, and refuses new runs until the question is settled.
Settling an unconfirmed run#
If pybox cleanup keeps reporting "unresolved create … a late object is possible", wait until the run is past its expiry plus one minute, then tell PyBox to retire it:
$ pybox cleanup --resolve-attempt 8f3a…c210 # the 32-character run ID from pending_attempts
PyBox looks one last time for a box with that exact name and labels. Only if that complete search is empty does it delete the note, and it records ABSENT_AFTER_EXPIRY, not "never created", because that still can't be proven. It never removes anything in this step. If a box did appear later, it would carry your installation's label and be cleaned up normally.
What the statuses mean#
| Status | Meaning |
|---|---|
REMOVED | Removed, then confirmed gone |
ABSENT | A known box was already gone |
NOT_CREATED | The engine definitely refused to create it, and a complete search found nothing |
UNCONFIRMED | PyBox can't prove the box is gone. It says so instead of guessing |
NOT_ATTEMPTED | Nothing was created, e.g. the VM wasn't running |
KEPT_UNEXPIRED | (during reconciliation) Not yet expired, so left alone |
ABSENT_AFTER_EXPIRY | (when settling an unconfirmed run) Past expiry and not found; the note was retired |