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

# Direct API Access with WrennClient and AsyncWrennClient

> WrennClient gives you direct access to Wrenn REST API resources — capsules, snapshots — without the high-level Capsule wrapper.

For advanced use cases where you need fine-grained control over individual API calls — building your own abstractions, batching operations, or calling endpoints without constructing a full `Capsule` object — use `WrennClient` or `AsyncWrennClient` directly.

```python theme={null}
from wrenn import WrennClient, AsyncWrennClient
```

<Note>
  `WrennClient` is what the high-level `Capsule` class uses internally. You only need to reach for it when the `Capsule` abstraction is not the right fit for your use case.
</Note>

## Synchronous client

Instantiate `WrennClient` with your API key and use it as a context manager to ensure the HTTP connection pool is closed when you're done:

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

with WrennClient(api_key="wrn_...") as client:
    capsule = client.capsules.create(template="minimal")
    print(capsule.id)
```

If you prefer managing the lifecycle manually, call `client.close()` when finished.

### Constructor parameters

| Parameter  | Type          | Default                                         | Description                    |
| ---------- | ------------- | ----------------------------------------------- | ------------------------------ |
| `api_key`  | `str \| None` | `WRENN_API_KEY` env var                         | Your Wrenn API key (`wrn_...`) |
| `base_url` | `str \| None` | `WRENN_BASE_URL` env var or production endpoint | Override the API base URL      |

<Tip>
  If `api_key` is not passed, the client reads `WRENN_API_KEY` from the environment. If neither is set, instantiation raises a `ValueError`. The `base_url` parameter is primarily useful when pointing at a staging environment or a self-hosted deployment.
</Tip>

## Capsule operations

`client.capsules` exposes all capsule control-plane operations:

```python theme={null}
with WrennClient(api_key="wrn_...") as client:
    # Create a new capsule
    capsule = client.capsules.create(template="minimal")

    # Get a capsule by ID
    capsule = client.capsules.get("cl-abc123")

    # List all capsules for the authenticated team
    all_capsules = client.capsules.list()

    # Pause a running capsule (snapshots memory state to disk)
    client.capsules.pause("cl-abc123")

    # Resume a paused capsule
    client.capsules.resume("cl-abc123")

    # Reset the inactivity timer to prevent auto-pause
    client.capsules.ping("cl-abc123")

    # Permanently destroy a capsule
    client.capsules.destroy("cl-abc123")
```

### `capsules.create` parameters

| Parameter     | Type          | Default | Description                                                          |
| ------------- | ------------- | ------- | -------------------------------------------------------------------- |
| `template`    | `str \| None` | `None`  | Template name to boot from                                           |
| `vcpus`       | `int \| None` | `None`  | Number of virtual CPUs                                               |
| `memory_mb`   | `int \| None` | `None`  | Memory in MiB                                                        |
| `timeout_sec` | `int \| None` | `None`  | Inactivity TTL in seconds before auto-pause; `0` disables auto-pause |

## Snapshot operations

`client.snapshots` lets you create, list, and delete snapshot templates:

```python theme={null}
with WrennClient(api_key="wrn_...") as client:
    # Create a snapshot from a running capsule
    template = client.snapshots.create(
        capsule_id="cl-abc123",
        name="my-snapshot",
    )

    # List all snapshot templates
    templates = client.snapshots.list()

    # Delete a snapshot template by name
    client.snapshots.delete("my-snapshot")
```

Snapshots capture the full filesystem and memory state of a capsule into a reusable template. Pass the template name to `capsules.create(template=...)` to boot a new capsule from it.

## Async client

`AsyncWrennClient` provides the same interface with `async`/`await` semantics. Use it as an async context manager:

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

async def main():
    async with AsyncWrennClient(api_key="wrn_...") as client:
        capsule = await client.capsules.create(template="minimal")

        templates = await client.snapshots.list()

        await client.capsules.destroy(capsule.id)

asyncio.run(main())
```

Every method on `AsyncWrennClient.capsules` and `AsyncWrennClient.snapshots` is a coroutine — prefix each call with `await`. To close the connection manually without a context manager, call `await client.aclose()`.

<Warning>
  `AsyncWrennClient` uses an `httpx.AsyncClient` internally. Do not share a single instance across multiple event loops. Create a new client per event loop or per request if you are using a framework that manages loop lifecycles (e.g. FastAPI, Starlette).
</Warning>