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: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: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, saveresult.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 withTemporalDurability 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_timeoutalso applies on reattachment. A command’stimeoutseparately 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.
Complete cookbook examples
- Pause/resume:
pydantic-ai-pythondiagnoses 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-pythonkills and restarts a worker after a durable diagnosis checkpoint, then verifies the same sandbox ID and no additional running/paused sandboxes. View cookbook.