> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI

> Run a Pydantic AI agent's commands and file edits on an isolated boxd machine, then come back to it or fork it.

![The Pydantic AI logo inside the boxd card.](https://mintcdn.com/azin/6pxNMFBT7Eg7ouNq/images/boxd-x-pydantic-ai.png?fit=max\&auto=format\&n=6pxNMFBT7Eg7ouNq\&q=85\&s=fa5b38ada164802465fba02be3974243)

[Pydantic AI](https://ai.pydantic.dev) is the Python agent framework from the team behind Pydantic. Its [Harness](https://pydantic.dev/docs/ai/harness/) adds ready-made capabilities, such as `Coder`, `Shell`, and `FileSystem`, that give an agent tools to run commands and edit files.

`BoxdSandbox` runs those tools on an isolated boxd machine instead of on your computer. It is part of the Harness, and the boxd team maintains it together with the Pydantic maintainers ([pull request](https://github.com/pydantic/pydantic-ai/pull/11367)).

## Set up

**1. Install the Harness with the boxd extra**

```bash theme={"theme":"github-dark"}
pip install 'pydantic-ai-harness[boxd,anthropic]'
```

The `anthropic` extra is for the example below; use your model provider's extra instead. `BoxdSandbox` ships in the first release after `pydantic-ai-harness` 0.63.0. Until then, install it from GitHub:

```bash theme={"theme":"github-dark"}
pip install 'pydantic-ai-harness[boxd,anthropic] @ git+https://github.com/pydantic/pydantic-ai.git#subdirectory=src/pydantic_ai_harness'
```

**2. Create an API key**

```bash theme={"theme":"github-dark"}
boxd auth keys create pydantic-ai --org <your-org>
export BOXD_API_KEY=bxd_...
```

Machines are created and billed in the key's organization.

**3. Give the agent a machine**

```python theme={"theme":"github-dark"}
from pydantic_ai import Agent
from pydantic_ai_harness.boxd_sandbox import BoxdSandbox
from pydantic_ai_harness.coder import Coder

agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[BoxdSandbox(), Coder()])
result = agent.run_sync('Clone https://github.com/pydantic/pydantic-ai and summarize how capabilities work.')
```

`Coder`'s shell and file tools now run on the machine. Set `ANTHROPIC_API_KEY` for the model.

## Come back to the machine

A follow-up run that gets the first run's message history works on the same machine, so the clone is still there. To come back later without the history, store the run's workspace ref and pass it back:

```python theme={"theme":"github-dark"}
ref = result.workspace.ref  # store this, for example in your database
later = agent.run_sync('Which capability would you add next?', workspace=ref)
```

If boxd suspended or stopped the machine in between, the next run wakes or starts it again.

## Fork a machine

`fork(ref)` copies a machine into a new isolated one, with its files and running processes as they are at that moment, and returns the copy's ref. Two agents can then try different approaches from the same starting point at once:

```python theme={"theme":"github-dark"}
copy = await BoxdSandbox().fork(ref)
await asyncio.gather(
    agent.run('Speed up the slowest test by caching what it builds.', workspace=ref),
    agent.run('Speed up the slowest test by mocking its network calls.', workspace=copy),
)
```

The two machines change independently after the fork.

## Clean up

Pydantic AI never deletes a machine. boxd suspends, and later hibernates, a machine that sits idle, and you delete one with its ref:

```python theme={"theme":"github-dark"}
await BoxdSandbox().destroy(ref)
```

Machines `BoxdSandbox` creates are named `pydantic-ai-<hex>`, so `boxd machine list` shows any that a crashed run left behind.

## What each machine gets

* **Isolation:** machines `BoxdSandbox` creates, and copies `fork` makes, are isolated: code the agent runs holds no boxd credentials and can't reach your other machines. `BoxdSandbox` refuses to attach to a machine that isn't isolated.
* **The default image:** Ubuntu 24.04 with git, Python 3, uv, Node.js, and ripgrep. For your own dependencies, start from a [snapshot](https://docs.boxd.sh/guides/snapshots.md) with `BoxdSandbox(snapshot='my-snapshot')`.
* **A size:** `BoxdSandbox(vcpu=4)` picks one of boxd's [machine sizes](https://docs.boxd.sh/guides/machine-specs.md), 1, 2, 4, or 8 vCPUs with 4 GiB each.
* **Files through boxd's file API:** writes create missing directories, go through symlinks, and keep a file's mode, all as the machine's non-root `boxd` user.
* **Commands as the `boxd` user,** who has passwordless `sudo`. A timeout or a cancelled run stops the command's whole process group.

The [Harness docs for `BoxdSandbox`](https://github.com/pydantic/pydantic-ai/blob/main/docs/harness/boxd-sandbox.md) cover the rest, including durable execution with Temporal, DBOS, and Prefect, the configuration reference, and the security model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.