Managing Capsule Lifecycle: Pause, Resume, Destroy

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()

Get Started

Capsules

Code Interpreter

Advanced

Reference

Managing Capsule Lifecycle: Pause, Resume, Destroy

Lifecycle states

Waiting for a capsule to be ready

Checking status

Pausing a capsule

Resuming a capsule

Destroying a capsule

Inactivity timeout and ping

Full lifecycle example

​Lifecycle states

​Waiting for a capsule to be ready

​Checking status

​Pausing a capsule

​Resuming a capsule

​Destroying a capsule

​Inactivity timeout and ping

​Full lifecycle example

Lifecycle states

Waiting for a capsule to be ready

Checking status

Pausing a capsule

Resuming a capsule

Destroying a capsule

Inactivity timeout and ping

Full lifecycle example