Skip to main content
Pydantic AI has a native E2B workspace provider in its official harness package. E2BSandbox supplies the execution environment; capabilities such as Shell, FileSystem, and Coder run their commands and file operations inside that environment. Pydantic AI manages the agent loop and workspace selection. E2B supplies the isolated computer and its persistent filesystem. Your application decides when to pause or delete the sandbox.

Install and authenticate

Use Python 3.11 or newer. Install the native integration and the model provider used below:
Set keys in the process running the agent:
The example uses gpt-4.1-mini to keep a small coding task inexpensive. Other providers need their corresponding Pydantic AI extra and model configuration. API keys remain on your machine; the sandbox does not inherit your environment.

Fix a Python log-analysis CLI

This CLI incorrectly counts only HTTP 500 responses as server errors. Seed a small project, let the agent fix it, and verify the actual output independently:
The result prints your sandbox ID and verified server errors: 2. The application checks the executed CLI rather than trusting the agent’s explanation. Internet access is disabled because this project needs no downloads; model calls happen on the host. The supplied backend owns the working directory, environment, and lifetime settings. The agent’s E2BSandbox() capability does not override those settings when workspace=backend is supplied. Initialization is inside try so a failed file upload or agent run still reaches cleanup.

Continue after a pause

To keep the workspace, save result.workspace.ref and result.all_messages() instead of deleting it after the first run. Get the underlying E2B SDK handle with await backend.get_sandbox() and pause it with await sandbox.pause(). For the second run, pass the saved ref as workspace= and the saved messages as message_history=. Configure E2BSandbox with the same working directory and environment for reattachment. The first workspace operation reconnects and resumes the paused sandbox; its files are still there. The ref identifies the workspace, while message history also preserves the conversation. A ref contains no credentials, so another process needs its own E2B_API_KEY. A killed or unavailable sandbox raises WorkspaceUnavailableError; the integration does not quietly replace it with a new empty sandbox. Use workspace="new" only when you intentionally want a separate workspace.

Recover a Temporal worker

Compose the agent with TemporalDurability from pydantic_ai.durable_exec.temporal, register it on a PydanticAIWorkflow, and connect the Temporal client with PydanticAIPlugin. Install the harness’s temporal extra too. The plugin registers model/tool/workspace activities for the workflow’s agents. Persist the workspace ref before testing a worker crash. A replacement worker uses the same task queue, workflow, agent registration, and ref to continue in that sandbox. Temporal replay preserves completed operations; activities interrupted before their completion is recorded may execute again. Make their side effects repeatable. Killing a worker is not proof that a remote shell command stopped, and recovery is not an exactly-once guarantee for sandbox creation.

Ownership and lifetime

  • Pydantic AI does not delete the sandbox at the end of an agent run. It can keep running and billing until you pause it, delete it, or its lifetime expires.
  • Native E2B sandboxes default to a 3,600-second lifetime and pause on timeout. sandbox_timeout also applies on reattachment. A command’s timeout separately bounds that command.
  • Call await E2BSandbox().destroy(ref) when the application is finished. It deletes a paused sandbox by ID without resuming it. Preserve the ref and report cleanup errors so deletion can be retried.
  • File tools and shell commands share the sandbox. File-tool path restrictions do not constrain arbitrary shell commands, and the model should not receive host-file transfer tools or API keys it does not need.
See E2B persistence, the native Pydantic AI guide, and Pydantic AI’s Temporal documentation.

Complete cookbook examples

  • Pause/resume: pydantic-ai-python diagnoses a JSONL log CLI, pauses the sandbox, then repairs it in a second run. It checks the same ID, preserved file checksums, original regression tests, and cleanup. View cookbook.
  • Temporal crash recovery: pydantic-ai-temporal-python kills and restarts a worker after a durable diagnosis checkpoint, then verifies the same sandbox ID and no additional running/paused sandboxes. View cookbook.