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