Direct API Access with WrennClient and AsyncWrennClient

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.

from wrenn import WrennClient, AsyncWrennClient

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.

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:

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

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.

Capsule operations

client.capsules exposes all capsule control-plane operations:

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:

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:

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().

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

Get Started

Capsules

Code Interpreter

Advanced

Reference

Direct API Access with WrennClient and AsyncWrennClient

Synchronous client

Constructor parameters

Capsule operations

`capsules.create` parameters

Snapshot operations

Async client

​Synchronous client

​Constructor parameters

​Capsule operations

​capsules.create parameters

​Snapshot operations

​Async client

Synchronous client

Constructor parameters

Capsule operations

`capsules.create` parameters

Snapshot operations

Async client