Metadata-Version: 2.3
Name: backyard
Version: 0.3.0
Summary: Fast Python sandboxes for AI agents.
Author: Ryan Parker
Requires-Dist: pydantic-monty>=0.0.19
Requires-Dist: textual[syntax]>=8.2.8 ; extra == 'tui'
Requires-Python: >=3.13
Project-URL: homepage, https://github.com/rparkr/backyard
Project-URL: repository, https://github.com/rparkr/backyard
Project-URL: documentation, https://rparkr.github.io/backyard
Provides-Extra: tui
Description-Content-Type: text/markdown

<div style="text-align: center">

<img
    alt="A logo with the word 'backyard' and an drawing of a sandbox with a shovel in it"
    src="docs/assets/backyard-logo.svg">
    <!-- style="width: 1280px; height: 160px; object-fit: cover; object-position: 55% 48%"> -->

</div>

> --> [_Documentation_](https://rparkr.github.io/backyard/)

# Backyard

Fast Python sandbox for AI agent harnesses.

`backyard` supports safe and transparent execution of Python code using either:
- [**Pydantic-Monty**](https://github.com/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`](https://github.com/astral-sh/uv) (recommended):

```shell
uv add backyard
```

Or, with `pip`:

```shell
pip install backyard
```

### Python API

```python
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:

```shell
uv add "backyard[tui]"
```

```shell
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.

![TUI demo](./docs/assets/backyard.gif)
_Demo recorded with [asciinema](https://github.com/asciinema/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**](https://github.com/google/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](https://gvisor.dev/docs/user_guide/install/)

<details><summary>Click to see instructions</summary>

1. Install the `runsc` binary:

   ```shell
   # Ubuntu / Debian
   sudo apt-get install runsc

   # Or download the latest release
   wget https://storage.googleapis.com/gvisor/releases/release/latest/runsc
   sudo mv runsc /usr/local/bin/runsc
   sudo chmod +x /usr/local/bin/runsc
   ```

2. Register `runsc` with your container engine by editing the daemon configuration:

   **Docker** — add to `/etc/docker/daemon.json`:
   ```json
   {
       "runtimes": {
           "runsc": {
               "path": "/usr/local/bin/runsc"
           }
       }
   }
   ```

   **Podman** — add to `~/.config/containers/containers.conf` or `/etc/containers/containers.conf`:
   ```ini
   [engine.runtimes]
   runsc = ["/usr/local/bin/runsc"]
   ```

3. Restart the container engine:
   ```shell
   # Docker
   sudo systemctl restart docker

   # Podman (no daemon, but verify the config is picked up)
   podman info --format '{{json .Host.OCIRuntimes}}'
   ```

Once configured, `backyard` will automatically detect and use gVisor for all container sandboxes, providing an additional kernel-level security boundary.

</details>

## 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](https://github.com/rparkr/lfm-coder) 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`](https://github.com/rparkr/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_](https://en.wikipedia.org/wiki/Sandbox_(computer_security)) 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) license.

## Acknowledgements
A big thank you to the following teams for their work that makes this project possible:
- The Pydantic team for creating [Monty](https://github.com/pydantic/monty), the Rust-based Python interpreter that powers the ultra-fast default sandbox in `backyard`.
- The [Podman](https://podman.io/) and [Docker](https://www.docker.com/) teams for building container runtimes that power the full-featured sandbox.
- The [Astral](https://astral.sh/) 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](https://github.com/textualize/textual/), the TUI framework that powers `backyard`'s notebook-like TUI.
- The [Zensical](https://github.com/zensical/zensical) team for the static site generator that powers `backyard`'s [documentation](https://rparkr.github.io/backyard) 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](https://dev.to/scofieldfree/i-built-a-browser-only-image-vectorizer-with-webassembly-3fnf) for creating [vectorize-image](https://vectorize-image.app/), which I used to convert the logo into SVG format
- The [marimo](https://github.com/marimo-team/marimo) team for maintaining the [list](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/packages/module_name_to_pypi_name.py) of import-to-PyPI package names used in `backyard` for automatic dependency installation
