> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wrenn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Wrenn Capsules: Isolated MicroVM Environments

> Learn how Wrenn capsules work — how to create, configure, and connect to isolated microVM environments for sandboxed code execution.

A capsule is an isolated [Firecracker](https://firecracker-microvm.github.io/) 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.

```python theme={null}
from wrenn import Capsule

capsule = Capsule()
```

You can pass configuration parameters at creation time:

```python theme={null}
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:

```python theme={null}
capsule = Capsule(template="minimal", wait=True)
```

`Capsule.create()` is a classmethod that is exactly equivalent to calling `Capsule()` directly:

```python theme={null}
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:

```python theme={null}
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.

```python theme={null}
capsule = Capsule.connect("cl-abc123")
result = capsule.commands.run("echo still running")
```

<Note>
  Capsule IDs always start with the `cl-` prefix (for example, `cl-abc123`).
</Note>

## Listing and inspecting capsules

```python theme={null}
# 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:

```python theme={null}
info = capsule.get_info()
```

## Destroying a capsule

```python theme={null}
# From an instance
capsule.destroy()

# Statically, by ID
Capsule.destroy("cl-abc123")
```

<Warning>
  Destroying a capsule is permanent. All data on the capsule's filesystem is deleted.
</Warning>

## What's next

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="rotate" href="/capsules/lifecycle">
    Pause, resume, and monitor capsule state.
  </Card>

  <Card title="Commands" icon="terminal" href="/capsules/commands">
    Run foreground, background, and streaming commands.
  </Card>

  <Card title="Filesystem" icon="folder" href="/capsules/filesystem">
    Read, write, and stream files inside a capsule.
  </Card>

  <Card title="Terminal" icon="square-terminal" href="/capsules/terminal">
    Open interactive PTY sessions inside a capsule.
  </Card>
</CardGroup>