Code mode is not a sandbox

#What code mode is

With ordinary tool calling, the model picks one tool, fills in JSON arguments, and waits. You run the tool, send the result back, and the model decides what to do next. When one call depends on another, each step costs a model request, and every intermediate result lands in the context window.

With code mode, the model gets a single tool, run_code, and writes a short Python program that calls your tools as functions. Loops, filters, and asyncio.gather run as code instead of as more turns of conversation. Cloudflare named the pattern, and Anthropic reached the same conclusion from the model side.

In Pydantic AI, code mode is the CodeMode capability from Pydantic AI Harness:

from typing import TypedDict

import logfire
from pydantic_ai import Agent
from pydantic_ai_harness import CodeMode

logfire.configure(service_name='code-mode')
logfire.instrument_pydantic_ai()


class Order(TypedDict):
    id: str
    total: float


ORDERS = {'cus_42': ['ord_1', 'ord_2', 'ord_3']}
TOTALS = {'ord_1': 120.0, 'ord_2': 35.5, 'ord_3': 210.0}

agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[CodeMode()])


@agent.tool_plain
def list_orders(customer_id: str) -> list[str]:
    """List the order IDs for a customer."""
    return ORDERS.get(customer_id, [])


@agent.tool_plain
def get_order(order_id: str) -> Order:
    """Fetch one order."""
    return Order(id=order_id, total=TOTALS[order_id])


result = agent.run_sync('How many orders over $100 does cus_42 have, and what is their total?')
print(result.output)

Install it with uv add "pydantic-ai-harness[codemode,anthropic,logfire]", and set your model provider API keys, in this case ANTHROPIC_API_KEY.

The model never sees list_orders and get_order as separate tools. It sees them as typed Python functions in the description of run_code:

class Order(TypedDict):
    id: str
    total: float

async def list_orders(*, customer_id: str) -> list[str]:
    """List the order IDs for a customer."""
    ...

async def get_order(*, order_id: str) -> Order:
    """Fetch one order."""
    ...

And it writes one program:

import asyncio

order_ids = await list_orders(customer_id='cus_42')
orders = await asyncio.gather(*[get_order(order_id=i) for i in order_ids])
big = [o for o in orders if o['total'] > 100]
{'count': len(big), 'total': sum(o['total'] for o in big)}

Without code mode, the model needs one request to list the orders, another to fetch them, and a third to answer, with every order in its context along the way. With code mode, it writes one program and reads back one small dict. The gap grows with every dependent step.

Here is that run traced in Logfire. list_orders and the three get_order calls sit inside the single run_code span, between the two model requests:

Explore the spans above, or open the full trace.

The program is type-checked against those signatures before it runs. A model that compares a string with an int gets a type error back as a retry instead of producing a wrong answer.

Jiri wrote about what this did for the Logfire MCP server, where three tools replaced more than forty.

#Code mode runs next to your agent

The program needs somewhere to run. In Pydantic AI, run_code runs in Monty, a Python interpreter written in Rust, in a pool of worker processes on the same machine as your agent.

Inside run_code, the program has no filesystem, no network, no environment variables, and no clock unless you hand them in. It reaches the outside world only by calling the functions you exposed. When it calls get_order, Monty pauses, Pydantic AI runs your real get_order in the agent's process, and the result goes back into the program.

So two things are true at once:

• The program is isolated. It can't open a socket or read ~/.ssh. By default, each run_code call gets 30 seconds, 256 MiB, and 100 nested tool calls.
• Your tools are not. get_order runs with whatever access your agent process has: database credentials, API keys, the host filesystem.

In code mode, the security boundary is the list of functions you expose. Put refund_order in that list and the model can write a loop that calls it 100 times. CodeMode(tools=['list_orders', 'get_order']) chooses which tools go inside run_code; the rest stay visible to the model as ordinary tool calls.

Monty also runs a subset of Python, with a short list of standard library modules and no third-party packages. The model can't pip install pandas, run pytest, or call git from inside it. For that you need a real execution environment: your own machine if you trust the work, or a sandbox if you don't.

#What a sandbox is

A sandbox is an isolated environment: a container, a microVM, a cloud VM, or a restricted process on your own machine. Unlike Monty, it usually has a real filesystem, a shell, and CPython, so the model can run ordinary programs. What those programs can run and reach depends on the sandbox's image, network rules, and mounts.

#Where the sandbox boundary goes

Once you need a sandbox, the next question is what goes inside it. There are three answers.

#Workspaces in Pydantic AI

A workspace is the environment an agent's tools work in: where commands run and where files are read and written. Tools reach it through ctx.workspace, and they don't know whether it is a directory on your laptop or a VM in the cloud.

import logfire
from pydantic_ai import Agent, ModelRetry, RunContext
from pydantic_ai.capabilities import LocalWorkspace
from pydantic_ai.workspaces import WorkspaceError

logfire.configure(service_name='workspaces')
logfire.instrument_pydantic_ai()

agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[LocalWorkspace('.')])


@agent.tool
async def execute(ctx: RunContext, command: list[str]) -> str:
    """Run a command in the project directory."""
    try:
        result = await ctx.workspace.run(command, timeout=60)
    except WorkspaceError as error:
        raise ModelRetry(str(error))
    return result.stdout if result.exit_code == 0 else f'[exit {result.exit_code}] {result.stderr}'


result = agent.run_sync('Write fizzbuzz to fizzbuzz.py and run it.')
print(result.output)

LocalWorkspace is not a sandbox. Commands run on your machine, as you, and the directory only sets where they start. They get PATH, HOME, and the locale variables and nothing else from your environment, so the model's commands don't inherit your API keys. Use it for your own, trusted work.

To isolate the agent, swap the workspace capability. execute keeps working unchanged, because it only talks to ctx.workspace.

You rarely need to write tools like execute yourself, though. The harness capabilities Coder, FileSystem, and Shell give the model file, search, and shell tools that work in whatever workspace the run has. This agent gets Coder in a Modal sandbox:

import logfire
from pydantic_ai import Agent
from pydantic_ai_harness import Coder, ModalSandbox

logfire.configure()
logfire.instrument_pydantic_ai()

agent = Agent('anthropic:claude-sonnet-5-5', capabilities=[ModalSandbox(), Coder()])

Install it with uv add "pydantic-ai-harness[modal,anthropic,logfire]", and log in to Modal with modal token new. Every command and file edit now happens in the sandbox.

This trace is the LocalWorkspace agent from earlier writing and running fizzbuzz. Each execute call is one span, with a model request on either side:

Explore the spans above, or open the full trace.

Pydantic AI and Pydantic AI Harness ship these workspaces:

A workspace outlives a single run. Once a run has used a sandbox, passing its message history to the next run continues in the same sandbox, with the same files and installed packages:

first = agent.run_sync('Clone https://github.com/pydantic/pydantic-ai and run its tests.')
second = agent.run_sync('Fix the first failing test.', message_history=first.all_messages())

#Code mode and a workspace together

Code mode and workspaces solve different problems, so they combine. Here the model's Python runs in Monty next to the agent, and the file tools it calls from that Python act in a Modal sandbox:

import logfire
from pydantic_ai import Agent
from pydantic_ai_harness import CodeMode, FileSystem, ModalSandbox, Shell

logfire.configure()
logfire.instrument_pydantic_ai()

agent = Agent(
    'anthropic:claude-sonnet-5-5',
    capabilities=[ModalSandbox(working_dir='/root/project'), FileSystem(), Shell(), CodeMode()],
)

result = agent.run_sync('Find every TODO in the project and summarize them by file.')
print(result.output)

Install it with uv add "pydantic-ai-harness[codemode,modal,anthropic,logfire]", and log in to Modal with modal token new.

The model sees three tools: run_code, run_command, and start_command. read_file, edit_file, list_directory, and the other file tools become functions inside run_code, so one program can read twenty files, filter them, and edit the three that matter. Shell commands stay outside as ordinary tool calls, so the model never has to quote a shell command inside a Python string.

Each layer has one job:

• The agent loop and your model key stay in your process.
• The program the model writes runs in Monty, which can reach only the functions you exposed.
• The file and shell tools act in the Modal sandbox, so edits and commands never touch your machine.

#Which one you need

#Monty

Code mode is cheap enough to leave on because of Monty. It is an MIT-licensed Python interpreter written in Rust, built for code written by models. You can use it without Pydantic AI, from Python, JavaScript, or Rust:

import logfire
from pydantic_monty import Monty

logfire.configure(service_name='monty')
logfire.instrument_monty()

code = """
kcal = nutrition('chocolate bar')['kcal']
hours = kcal * 4184 / (bulb_watts * 3600)
print(f'a chocolate bar powers a {bulb_watts} W bulb for {hours:.1f} hours')
"""

with Monty() as pool:
    with pool.checkout() as session:
        session.feed_run(
            code,
            inputs={'bulb_watts': 10},
            external_lookup={'nutrition': lambda food: {'kcal': 230}},
        )
        #> a chocolate bar powers a 10 W bulb for 26.7 hours

Monty() starts a monty worker process, and code runs inside it. inputs puts a variable called bulb_watts in the sandbox, with the value 10. external_lookup lets code call nutrition, but the function stays in your own Python process. When code calls nutrition('chocolate bar'), the worker waits, your process runs the function, and {'kcal': 230} goes back to code. code can call the function and read what it returns, but the function itself never runs inside Monty.

Install it with uv add pydantic-monty logfire.