Metadata-Version: 2.3
Name: backyard
Version: 0.2.0
Summary: Fast Python sandboxes for AI agents.
Author: Ryan Parker
Requires-Dist: pydantic-monty>=0.0.18
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
Provides-Extra: tui
Description-Content-Type: text/markdown

# Backyard

Fast Python Sandbox for AI agent harnesses.

`backyard` supports transparent execution of Python code using either:
- [Pydantic-Monty](https://github.com/pydantic/monty): an ultra-fast, minimal Python interpreter
- a container engine (Docker or Podman): 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 pprint import pprint

from backyard import Sandbox

sandbox = Sandbox()

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

result = sandbox.run(code)

pprint(result)
```

## Security

### 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

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.

## FAQ

### Why did you create this?
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 model-generated code and generate rewards for training the model.

I then expanded the sandbox capabilities for use in the [`my-ai`](https://github.com/rparkr/my-ai) coding agent harness I am building.

### 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 does one place a sandbox? In the **backyard**.
