Wrenn Capsules: Isolated MicroVM Environments

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.

Get Started

Capsules

Code Interpreter

Advanced

Reference

Wrenn Capsules: Isolated MicroVM Environments

Creating a capsule

Context manager

Connecting to an existing capsule

Listing and inspecting capsules

Destroying a capsule

What’s next

Lifecycle

Commands

Filesystem

Terminal

​Creating a capsule

​Context manager

​Connecting to an existing capsule

​Listing and inspecting capsules

​Destroying a capsule

​What’s next

Lifecycle

Commands

Filesystem

Terminal

Creating a capsule

Context manager

Connecting to an existing capsule

Listing and inspecting capsules

Destroying a capsule

What’s next