# Pydantic AI code execution tool: run code in a sandbox with any model

Pass `sandbox_tools(sbx)` to a Pydantic AI `Agent`. Every command then runs in
a Runtime microVM, whichever model provider you use.

**On Runtime, code execution does not depend on the model provider.** Pydantic
AI's native `CodeExecutionTool` asks the provider to run the code. It works with
some providers and not others, and the code runs on the provider's machines.
With Runtime's four sandbox tools, the model only chooses a command. The command
runs in a Firecracker microVM that your application created, under your network
rules and your spending cap. A 2 vCPU, 4 GiB sandbox costs $0.03125 an hour
while the model thinks, and $0.08 an hour with both CPUs busy.
pydantic-ai 2.61.0 was the current PyPI release on 25 October 2026.

## Native tool or sandbox tools?

| Question                   | `CodeExecutionTool` (native)                                             | Runtime `sandbox_tools`                                  |
| -------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------- |
| Which models               | OpenAI Responses, Google, Anthropic, xAI, Bedrock (Nova 2.0 models only) | Any model Pydantic AI supports, including `TestModel`    |
| Not supported              | Groq, OpenAI Chat Completions, Mistral, Cohere, Hugging Face             | None                                                     |
| Where code runs            | The provider's own environment                                           | A Runtime microVM with its own kernel                    |
| What the model gets        | The provider's code tool                                                 | A shell, file reads and writes, a directory listing      |
| Packages, files, processes | Whatever the provider's environment allows                               | Ubuntu 24.04 with `pip`, `apt` and `sudo`; files persist |
| Network                    | The provider's policy                                                    | Your allow-list, or internet off                         |

The provider list comes from Pydantic AI's own native tools page. Enable the
native tool as a capability:

```python check
from pydantic_ai import Agent, CodeExecutionTool
from pydantic_ai.capabilities import NativeTool

agent = Agent("anthropic:claude-sonnet-4-6", capabilities=[NativeTool(CodeExecutionTool())])
```

## The Runtime version

Pydantic AI registers plain functions passed in `tools=[...]`. It builds each
schema from the function signature and takes parameter descriptions from the
docstring. The four Runtime functions carry both. This is the whole
integration, as the [framework guide](/docs/frameworks#pydantic-ai) shows it:

```bash no-run
pip install pydantic-ai withruntime
```

```python check
from pydantic_ai import Agent
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


def solve(model, task: str) -> str:
    with Sandbox.create() as sbx:
        return Agent(model, tools=sandbox_tools(sbx)).run_sync(task).output
```

`model` is a model string in Pydantic AI's `provider:model` form, such as the
`"anthropic:claude-sonnet-4-6"` in its own docs, or a model object. The sandbox
stops when `solve` returns, even after an exception.

## Test the agent without a model

Pydantic AI's `TestModel` calls every tool it is given, with generated
arguments, and returns their results as JSON. Used with a real sandbox, it
tests the wiring from end to end without a model bill:

```python check
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from withruntime import Sandbox
from withruntime.tools import sandbox_tools

with Sandbox.create(network={"internet": False}) as sbx:
    result = Agent(TestModel(), tools=sandbox_tools(sbx)).run_sync("smoke test")
    print(result.output)  # {"runtime_exec": {"exit_code": ..., "stdout": ...}, ...}
```

This ran against pydantic-ai 2.49.0 on 25 September 2026. All four tools were
called.

## A data agent with a typed answer

Pydantic AI's `output_type` works well with a sandbox. The model does the work
with real code, and the answer comes back validated.

```python check
from pydantic import BaseModel
from pydantic_ai import Agent
from withruntime import Sandbox
from withruntime.tools import sandbox_tools


class Summary(BaseModel):
    rows: int
    mean_price: float


def summarize(model, csv_text: str) -> Summary:
    with Sandbox.create(
        network={"internet": True, "allow": ["pypi.org", "*.pythonhosted.org"]},
        timeout_seconds=600,
        on_lease_end="stop",
    ) as sbx:
        sbx.files.write("/workspace/prices.csv", csv_text)
        agent = Agent(
            model,
            output_type=Summary,
            tools=sandbox_tools(sbx),
            instructions="prices.csv is in the working directory. Use pandas to answer.",
        )
        return agent.run_sync("How many rows, and what is the mean price?").output
```

The file is written before the agent starts, so the data never passes through
the model's context. For more on this pattern, see
[a data analysis agent](/use-cases/data-analysis-agent).

## Keep the account safe

- **The model sees tools, not credentials.** Your application creates the
  sandbox. The model picks commands and paths inside it. It cannot reach the
  account or pick another sandbox.
- **Keys the code needs stay outside the sandbox.** A token stored as a Runtime
  secret appears in the sandbox as a placeholder. The host adds the real value
  only on HTTPS requests to the hosts you named
  ([secrets](/docs/security#secrets-sandboxes-never-see)).
- **Spending has two ceilings.** `max_total_cost_micros` on the create stops a
  sandbox once its total cost reaches that value. A daily spending limit on the
  application's key refuses any request past it with `spending_limit_reached`.
- **Async agents** get coroutine tools. Pass an `AsyncSandbox` to
  `sandbox_tools` and use `await agent.run(...)`.

## Which one to use

Use `CodeExecutionTool` when you already use a supported provider and short
scripts in the provider's environment are enough. Use Runtime when you switch
providers, test with `TestModel`, need packages or files that persist through
the run, or must control what the code can reach.

Related: [code interpreter](/glossary/code-interpreter),
[the OpenAI code interpreter alternative](/compare/openai-code-interpreter-alternative)
and [the Claude code execution tool alternative](/compare/claude-code-execution-tool-alternative).
A new account gets 100 free hours of a 1 GB machine in its first 30 days, with no card:

```bash no-run
printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
npx withruntime sandboxes run -- python3 - < invoice.py
```

## Sources

- [Pydantic AI: Native tools](https://pydantic.dev/docs/ai/native-tools/), `CodeExecutionTool` and its provider table, read 25 October 2026
- [Pydantic AI: Function tools](https://pydantic.dev/docs/ai/tools/), read 25 October 2026
- [pydantic-ai on PyPI](https://pypi.org/project/pydantic-ai/), version 2.61.0, read 25 October 2026

Facts on this page were checked on 25 October 2026.