# Wrenn

> Secure infrastructure for AI Agents

## Docs

- [Use AsyncCapsule for Non-Blocking Capsule Operations](https://docs.wrenn.dev/advanced/async.md): Wrenn provides AsyncCapsule and AsyncWrennClient for async Python applications. All capsule operations have async equivalents using await.
- [Git Operations Inside Wrenn Capsules](https://docs.wrenn.dev/advanced/git.md): Use capsule.git to run Git operations inside a capsule — init, clone, commit, push, pull, and branch management with credential support.
- [Create Reusable Capsule Templates with Snapshots](https://docs.wrenn.dev/advanced/snapshots.md): Snapshots capture a running capsule's full state as a reusable template. Boot new capsules from your snapshot using its name as the template parameter.
- [POST /v1/capsules — Create a capsule](https://docs.wrenn.dev/api-reference/capsules/create.md): POST /v1/capsules — Create a new capsule. Accepts template, vcpus, memory_mb, and timeout_sec. Returns the capsule object with its ID and status.
- [DELETE /v1/capsules/{id} — Destroy a capsule](https://docs.wrenn.dev/api-reference/capsules/destroy.md): DELETE /v1/capsules/{id} — Permanently destroy a capsule and release all resources. Returns 204 No Content. This action is irreversible.
- [GET /v1/capsules/{id} — Get capsule details](https://docs.wrenn.dev/api-reference/capsules/get.md): GET /v1/capsules/{id} — Retrieve details for a specific capsule by ID. Returns status, template, resource allocation, and timestamps.
- [GET /v1/capsules — List all capsules](https://docs.wrenn.dev/api-reference/capsules/list.md): GET /v1/capsules — List all capsules for your team. Returns an array of capsule objects including ID, status, template, and resource configuration.
- [POST /v1/capsules/{id}/pause — Pause a capsule](https://docs.wrenn.dev/api-reference/capsules/pause.md): POST /v1/capsules/{id}/pause — Snapshot a running capsule's state to disk and release all VM resources. The capsule can be resumed later.
- [POST /v1/capsules/{id}/ping — Reset inactivity timer](https://docs.wrenn.dev/api-reference/capsules/ping.md): POST /v1/capsules/{id}/ping — Reset the capsule's inactivity timer to prevent auto-pause. Use as a keepalive for idle but active capsules.
- [POST /v1/capsules/{id}/resume — Resume a paused capsule](https://docs.wrenn.dev/api-reference/capsules/resume.md): POST /v1/capsules/{id}/resume — Restore a paused capsule from its snapshot. Boots a fresh VM and restores state. Returns the updated capsule.
- [POST /v1/capsules/{id}/exec — Execute a command](https://docs.wrenn.dev/api-reference/execution/exec.md): POST /v1/capsules/{id}/exec — Execute a shell command inside a capsule. Supports foreground (blocking) and background (non-blocking) execution modes.
- [Stream command output via WebSocket](https://docs.wrenn.dev/api-reference/execution/exec-stream.md): GET /v1/capsules/{id}/exec/stream — WebSocket endpoint for streaming command execution. Receive stdout/stderr events in real time as they arrive.
- [Manage Running Processes in a Wrenn Capsule](https://docs.wrenn.dev/api-reference/execution/processes.md): List and kill processes running inside a capsule. GET /v1/capsules/{id}/processes lists all processes; DELETE kills by PID or tag.
- [Interactive PTY Terminal via WebSocket](https://docs.wrenn.dev/api-reference/execution/pty.md): GET /v1/capsules/{id}/pty — WebSocket endpoint for interactive PTY sessions. Supports starting, reconnecting, resizing, and killing terminal sessions.
- [POST /v1/capsules/{id}/files/read — Download a file](https://docs.wrenn.dev/api-reference/files/download.md): POST /v1/capsules/{id}/files/read — Download a file from inside a capsule. Returns raw binary content as application/octet-stream.
- [List directory contents in a capsule](https://docs.wrenn.dev/api-reference/files/list.md): POST /v1/capsules/{id}/files/list — List files and directories at a given path inside a capsule. Returns name, type, size, and modification time.
- [Create Directories and Remove Files in a Capsule](https://docs.wrenn.dev/api-reference/files/manage.md): Use POST /v1/capsules/{id}/files/mkdir to create directories and POST /files/remove to delete files or directories inside a capsule.
- [POST /v1/capsules/{id}/files/write — Upload a file](https://docs.wrenn.dev/api-reference/files/upload.md): POST /v1/capsules/{id}/files/write — Upload a file to a specific path inside a capsule. Use multipart/form-data with the path and file fields.
- [POST /v1/snapshots — Create a capsule snapshot template](https://docs.wrenn.dev/api-reference/snapshots/create.md): POST /v1/snapshots — Snapshot a running capsule into a reusable template. The capsule is paused and destroyed; use the template name to boot new capsules.
- [DELETE /v1/snapshots/{name} — Delete a snapshot template](https://docs.wrenn.dev/api-reference/snapshots/delete.md): DELETE /v1/snapshots/{name} — Permanently delete a snapshot template by name. Removes files from disk and the database record. This cannot be undone.
- [GET /v1/snapshots — List available capsule templates](https://docs.wrenn.dev/api-reference/snapshots/list.md): GET /v1/snapshots — List all capsule templates available to your team. Filter by type=base or type=snapshot. Use the name field with POST /v1/capsules.
- [Authentication](https://docs.wrenn.dev/authentication.md): Generate an API key from the Wrenn dashboard and authenticate using WRENN_API_KEY, the api_key constructor argument, or the X-API-Key HTTP header.
- [Run Commands Inside a Wrenn Capsule](https://docs.wrenn.dev/capsules/commands.md): Execute shell commands inside capsules using capsule.commands. Supports foreground, background, and streaming execution with full stdout/stderr capture.
- [Read and Write Files in a Wrenn Capsule](https://docs.wrenn.dev/capsules/filesystem.md): Access the capsule filesystem via capsule.files. Write text or bytes, read files, list directories, and stream large files without buffering.
- [Managing Capsule Lifecycle: Pause, Resume, Destroy](https://docs.wrenn.dev/capsules/lifecycle.md): Control capsule state with pause, resume, and destroy operations. Understand how Wrenn preserves running capsules via snapshot-based persistence.
- [Wrenn Capsules: Isolated MicroVM Environments](https://docs.wrenn.dev/capsules/overview.md): Learn how Wrenn capsules work — how to create, configure, and connect to isolated microVM environments for sandboxed code execution.
- [Interactive PTY Sessions Inside Wrenn Capsules](https://docs.wrenn.dev/capsules/terminal.md): Open an interactive terminal (PTY) session inside a capsule using capsule.pty(). Sessions survive WebSocket disconnects and can be reconnected by tag.
- [Run Python Code with run_code() in Wrenn](https://docs.wrenn.dev/code-interpreter/execution.md): Use capsule.run_code() to execute Python cells and capture results, logs, and errors. Supports streaming callbacks for real-time output.
- [Stateful Code Execution with Wrenn Code Interpreter](https://docs.wrenn.dev/code-interpreter/overview.md): The Wrenn code interpreter runs Python code in a persistent Jupyter kernel inside a capsule, preserving state across multiple run_code calls.
- [Handle Rich Output from Code Interpreter: Charts and Images](https://docs.wrenn.dev/code-interpreter/rich-output.md): Wrenn's code interpreter captures rich outputs like matplotlib charts, pandas DataFrames, and HTML — available as typed MIME fields on each Result.
- [Introduction](https://docs.wrenn.dev/introduction.md): Wrenn lets you create isolated microVM capsules, run commands, manage files, and execute stateful Python code — all from a clean Python SDK.
- [Python SDK Reference](https://docs.wrenn.dev/python-sdk-reference.md)
- [Quick Tour](https://docs.wrenn.dev/quickstart.md): Install the Wrenn Python SDK, set your API key, and run your first capsule in four steps. Includes a code interpreter example.
- [Wrenn SDK Error Types and HTTP Status Codes](https://docs.wrenn.dev/reference/errors.md): All Wrenn SDK errors inherit from WrennError and expose .code, .message, and .status_code. Use typed exceptions to handle specific failure modes.
- [Direct API Access with WrennClient and AsyncWrennClient](https://docs.wrenn.dev/reference/low-level-client.md): WrennClient gives you direct access to Wrenn REST API resources — capsules, snapshots — without the high-level Capsule wrapper.

## OpenAPI Specs

- [openapi](https://docs.wrenn.dev/api-reference/openapi.json)