Skip to main content
A capsule is an isolated Firecracker microVM managed by Wrenn. Each capsule gets its own kernel, filesystem, and network namespace, so code running inside one capsule cannot affect any other. You interact with capsules through the Capsule class in the Python SDK — creating them, running commands, reading files, and opening terminals — then destroy them when you’re done.

​
Creating a capsule

The simplest way to create a capsule is to construct a Capsule directly. The SDK reads your API key from the WRENN_API_KEY environment variable and starts the capsule immediately. 
from wrenn import Capsule

capsule = Capsule()
You can pass configuration parameters at creation time: 
capsule = Capsule(
    template="base-python",  # template name; defaults to "minimal"
    vcpus=2,                 # virtual CPU count
    memory_mb=1024,          # memory in MiB
    timeout=300,             # inactivity TTL in seconds before auto-pause; 0 = disabled
)
The wait=True parameter blocks until the capsule reaches running status before returning: 
capsule = Capsule(template="minimal", wait=True)
Capsule.create() is a classmethod that is exactly equivalent to calling Capsule() directly: 
capsule = Capsule.create(template="minimal", wait=True)

​
Context manager

Use a capsule as a context manager to ensure it is destroyed automatically when the block exits, even if an exception is raised: 
with Capsule(template="minimal", wait=True) as capsule:
    result = capsule.commands.run("echo hello")
    print(result.stdout)  # "hello\n"
# capsule is destroyed here

​
Connecting to an existing capsule

Attach to a capsule that is already running (or paused) using its ID. If the capsule is paused, connect resumes it automatically before returning. 
capsule = Capsule.connect("cl-abc123")
result = capsule.commands.run("echo still running")
Capsule IDs always start with the cl- prefix (for example, cl-abc123).

​
Listing and inspecting capsules

# List all capsules for your team
capsules = Capsule.list()
for c in capsules:
    print(c.id, c.status)

# Fetch current info for a specific capsule
info = Capsule.get_info("cl-abc123")
print(info.status)    # "running"
print(info.template)  # "minimal"
On an instance, get_info() refreshes and returns the latest metadata: 
info = capsule.get_info()

​
Destroying a capsule

# From an instance
capsule.destroy()

# Statically, by ID
Capsule.destroy("cl-abc123")
Destroying a capsule is permanent. All data on the capsule’s filesystem is deleted.

​
What’s next

Lifecycle

Pause, resume, and monitor capsule state.

Commands

Run foreground, background, and streaming commands.

Filesystem

Read, write, and stream files inside a capsule.

Terminal

Open interactive PTY sessions inside a capsule.