Every capsule moves through a defined set of states from creation to destruction. Understanding those states lets you build reliable workflows: pausing idle capsules to save resources, resuming them instantly when needed, and cleaning up with confidence.
Lifecycle states
| State | Description |
|---|
pending | Capsule is queued and waiting to be scheduled on a host. |
starting | Capsule is booting — the microVM kernel is starting up. |
running | Capsule is fully booted and ready to accept commands. |
paused | Capsule state has been snapshotted to disk and the VM has stopped. |
stopped | Capsule has exited and cannot be resumed. |
error | Capsule entered an unrecoverable error state. |
When you pause a capsule, Wrenn writes the full VM state — memory, processes, open files — to disk as a snapshot. Resuming restores that snapshot, so the capsule comes back exactly as you left it.
Waiting for a capsule to be ready
After creating a capsule without wait=True, call wait_ready() to block until it reaches running status:
capsule = Capsule(template="minimal")
capsule.wait_ready(timeout=30, interval=0.5)
wait_ready raises TimeoutError if the capsule does not reach running within timeout seconds. It raises RuntimeError if the capsule enters error, stopped, or paused state while waiting.
Checking status
# Live check — makes an API call
if capsule.is_running():
print("capsule is ready")
# Fetch full metadata
info = capsule.get_info()
print(info.status) # "running"
print(info.vcpus) # 1
print(info.memory_mb) # 512
Pausing a capsule
Pausing snapshots the running VM to disk and frees the host CPU and memory. The capsule’s filesystem and process state are preserved exactly.
# Instance method
capsule.pause()
# Static method — no instance required
Capsule.pause("cl-abc123")
Resuming a capsule
Resume restores the snapshot and brings the capsule back to running. Memory, processes, and open file descriptors are all restored.
# Instance method
capsule.resume()
# Static method
Capsule.resume("cl-abc123")
Capsule.connect() also resumes a paused capsule automatically:
capsule = Capsule.connect("cl-abc123") # resumes if paused
Destroying a capsule
Destroying a capsule permanently deletes the VM and all data on its filesystem.
# Instance method
capsule.destroy()
# Static method
Capsule.destroy("cl-abc123")
Destruction is irreversible. Create a snapshot first if you need to preserve the capsule’s state as a reusable template.
Inactivity timeout and ping
When you create a capsule with a timeout value, the capsule is automatically paused after that many seconds of inactivity. An activity is any exec or ping call.
Call ping() to reset the inactivity timer without executing a command:
import time
capsule = Capsule(template="minimal", timeout=60, wait=True)
# Keep the capsule alive during a long-running local operation
for _ in range(10):
time.sleep(30)
capsule.ping()
Set timeout=0 to disable auto-pause entirely. Use this for capsules that must stay running regardless of activity.
Full lifecycle example
from wrenn import Capsule
# Create and wait for ready
capsule = Capsule(template="minimal", timeout=120, wait=True)
print(capsule.capsule_id) # "cl-abc123"
print(capsule.is_running()) # True
# Do some work
capsule.commands.run("python train.py")
# Pause to save resources
capsule.pause()
info = capsule.get_info()
print(info.status) # "paused"
# Resume later and continue
capsule.resume()
capsule.wait_ready()
capsule.commands.run("python eval.py")
# Clean up
capsule.destroy()
