Lifecycle & persistence
A wisp’s mode controls when it stops, restarts, or is deleted.
| Mode | Behavior | Credential |
|---|---|---|
ephemeral |
Stops when idle; stops at its lifetime limit; deletes after remaining stopped | API or person token |
on-demand |
Stops when idle; the next work request starts it; keeps its disk | Person token |
always |
Restarts on the same host after VM failure or host reboot, unless explicitly stopped | Person token |
API and SDK creates default to ephemeral. The CLI and web console request on-demand for interactive workspaces. Older wisps without a mode keep their existing behavior until you set one.
Ephemeral defaults
Section titled “Ephemeral defaults”- Idle timeout: 5 minutes.
- Maximum lifetime: 1 hour.
- Automatic deletion: after 1 hour stopped.
Set idle_timeout_seconds, max_lifetime_seconds, and delete_after_stopped_seconds when creating or updating a wisp. Read lifetime_ends_at and delete_at in its response to see its deadlines.
Before its lifetime ends, work on a stopped ephemeral wisp starts it and cancels its pending deletion. After the lifetime ends, work returns HTTP 409. A person token can switch it to on-demand to keep using it. An automatically deleted wisp returns HTTP 410 to its owner for 24 hours.
Stops and wake-up
Section titled “Stops and wake-up”Commands, file operations, session attach, and port proxy requests start a stopped wisp. Listing wisps, reading their info, and listing sessions leave them stopped.
Files and installed packages persist across a stop and start. Memory and running processes do not. An always restart starts the VM; use your own process manager if you need an application to start with it. Recovery is on the same host.
Keep or delete
Section titled “Keep or delete”Use PATCH /v1/wisps/{name} with {"mode":"on-demand"} and a person token to keep a sandbox. Python and TypeScript offer w.keep().
Deleting a wisp permanently removes its disk and checkpoints. A local checkpoint is useful for rollback; it is not a backup against losing the host.