--> Documentation

Backyard

Fast Python sandbox for AI agent harnesses.

backyard supports safe and transparent execution of Python code using either:

• Pydantic-Monty: an ultra-fast, minimal Python interpreter written in Rust
• A container (Docker or Podman) with full-featured Python support

Getting started

Installation

Using uv (recommended):

uv add backyard

Or, with pip:

pip install backyard

Python API

from backyard import Sandbox

sandbox = Sandbox()

code = """
print("hello from the sandbox! 🏖🏰")
"""

result = sandbox.run(code)

print(result.stdout)

TUI

backyard comes with a notebook-like Text-based User Inferface (TUI) for trying out the sandboxes in your terminal. It requires the tui extra:

uv add "backyard[tui]"

uv run backyard

# Or, if you've activated the .venv already, you can run:
# backyard

Here's an example of the built-in TUI for accessing the sandboxes in a notebook-like environment.

It uses the Monty sandbox by default and transparently switches to a container-backed sandbox when executing code that requires third-party Python libraries or network access.

Demo recorded with asciinema.

Security

Both sandbox backends provide strong security measures for running agent-generated code: read-only file mounting, resource constraints (memory, CPU usage, timeouts), and network restrictions.

For an added layer of security for container-based sandboxes, backyard supports the gVisor container runtime.

gVisor (runsc) sandboxing

For maximum isolation when running untrusted code, backyard automatically detects and uses gVisor (runsc) as the container runtime if it is registered with your container engine. gVisor provides an additional kernel-level security boundary between the sandboxed code and the host system.

If gVisor is not detected, backyard falls back to the default runc runtime and logs a warning.

Installing gVisor

FAQ

Why did you create this?

To power the code execution tool for an AI coding agent harness I'm developing.

Originally, I built the dual-engine sandbox for fine-tuning large language models using Reinforcement Learning from Verifiable Rewards (RLVR) with Group Relative Policy Optimization (GRPO). The sandbox provided an environment to safely execute parallel batches of model-generated code, computing rewards for training the model.

I modified and expanded the sandbox capabilities for use in the breeze coding agent harness I am building.

To adapt the sandbox to the needs of AI agents, I replaced the stateless, parallel execution approach with a stateful system that enables agents to execute code interactively, like a Python notebook or advanced REPL.

Where does the name backyard come from?

The term sandbox refers to a controlled environment where untrusted code can be run safely.

In the physical world, a sandbox is a place where children explore and imagine as they create and shape the world around them. 🏖🏰

Where are sandboxes placed? In the backyard.

License

This project is distributed under the MIT license.

Acknowledgements

A big thank you to the following teams for their work that makes this project possible:

• The Pydantic team for creating Monty, the Rust-based Python interpreter that powers the ultra-fast default sandbox in backyard.
• The Podman and Docker teams for building container runtimes that power the full-featured sandbox.
• The Astral team for developing amazing tooling: the uv package manager (used in the full-featured sandbox), the ruff linter, and the ty type checker.
• Will McGugan and contributors to Textual, the TUI framework that powers backyard's notebook-like TUI.
• The Zensical team for the static site generator that powers backyard's documentation site.
• Google's Gemini team for Gemini 3.6 Flash and the Nano Banana image-generation model, which I used to design the logo.
• Scofield Eric for creating vectorize-image, which I used to convert the logo into SVG format
• The marimo team for maintaining the list of import-to-PyPI package names used in backyard for automatic dependency installation