> ## 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.

# Use AsyncCapsule for Non-Blocking Capsule Operations

> Wrenn provides AsyncCapsule and AsyncWrennClient for async Python applications. All capsule operations have async equivalents using await.

`AsyncCapsule` is the async counterpart to `Capsule`. Every method that performs I/O — running commands, reading and writing files, pausing and resuming, opening a PTY — has an `async` equivalent that you `await`. The interface is identical to the sync API; the only difference is the `await` keyword and the `async with` context manager.

## Creating an async capsule

Use `await AsyncCapsule.create(...)` to create a capsule, then use it as an async context manager. The capsule is destroyed automatically when the block exits.

```python theme={null}
import asyncio
from wrenn import AsyncCapsule

async def main():
    async with await AsyncCapsule.create(template="minimal", wait=True) as capsule:
        result = await capsule.commands.run("echo hello")
        print(result.stdout)  # "hello\n"

asyncio.run(main())
```

## Commands and files

All command and file operations are awaitable:

```python theme={null}
async with await AsyncCapsule.create(template="minimal", wait=True) as capsule:
    # Run a command
    result = await capsule.commands.run("echo hello")
    print(result.stdout)

    # Write and list files
    await capsule.files.write("/app/data.txt", "hello world")
    entries = await capsule.files.list("/app")
    for entry in entries:
        print(entry.name, entry.type)
```

## Lifecycle operations

`pause` and `resume` are awaitable just like the sync versions:

```python theme={null}
await capsule.pause()
await capsule.resume()
```

## Async code interpreter

Import `AsyncCapsule` from `wrenn.code_interpreter` for stateful async code execution:

```python theme={null}
from wrenn.code_interpreter import AsyncCapsule

async def main():
    async with await AsyncCapsule.create(wait=True) as capsule:
        result = await capsule.run_code("2 + 2")
        print(result.text)  # "4"
```

## Async PTY

Use `capsule.pty()` as an async context manager and iterate over events with `async for`:

```python theme={null}
import sys

async with capsule.pty(cmd="/bin/bash") as term:
    await term.write(b"ls -la\n")
    async for event in term:
        if event.type == "output":
            sys.stdout.buffer.write(event.data)
        elif event.type == "exit":
            break
```

<Note>
  `AsyncCapsule` mirrors the sync `Capsule` API exactly — every method has the same name and accepts the same parameters. The only change is adding `await` and using `async with` / `async for` where appropriate.
</Note>