Pydantic AI

Pydantic AI is the Python agent framework from the team behind Pydantic. Its 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).

Set up

Install the Harness with the boxd extra

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:

pip install 'pydantic-ai-harness[boxd,anthropic] @ git+https://github.com/pydantic/pydantic-ai.git#subdirectory=src/pydantic_ai_harness'

Create an API key

boxd auth keys create pydantic-ai --org <your-org>
export BOXD_API_KEY=bxd_...

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

Give the agent a machine

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:

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:

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:

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 with BoxdSandbox(snapshot='my-snapshot').
A size: BoxdSandbox(vcpu=4) picks one of boxd’s machine sizes, 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 cover the rest, including durable execution with Temporal, DBOS, and Prefect, the configuration reference, and the security model.

Getting started

Guides

Integrations and automations

Use cases

References

Pydantic AI

Set up

Come back to the machine

Fork a machine

Clean up

What each machine gets

​Set up

​Come back to the machine

​Fork a machine

​Clean up

​What each machine gets

Set up

Come back to the machine

Fork a machine

Clean up

What each machine gets