Add sandbox

README.md

@@ -38,6 +38,30 @@ Herald reads its configuration from environment variables (a `.env` file is supp
 | `METRICS_BIND_ADDR` | *(optional)* Bind address for the Prometheus metrics endpoint (e.g. `0.0.0.0:9100`). If unset, the metrics exporter is disabled. |
 | `SENTRY_DSN` | *(optional)* Sentry DSN for error tracking |
 | `RUST_LOG` | *(optional)* Log level, defaults to `info` |
+| `SANDBOX_ENABLED` | *(optional)* Run reviews inside a devcontainer sandbox so the model can explore the repository with tools. Defaults to `false` |
+| `CONTAINER_RUNTIME` | *(optional)* Container runtime binary used for the sandbox (`docker` or `podman`). Defaults to `docker` |
+| `SANDBOX_MAX_ITERATIONS` | *(optional)* Maximum number of tool-calling iterations per sandboxed review. Defaults to `8` |
+
+## Sandboxed reviews
+
+When `SANDBOX_ENABLED=true`, Herald reviews pull requests inside an ephemeral
+[Dev Container](https://containers.dev/). For each review it:
+
+1. clones the pull request head into a temporary directory,
+2. builds and starts the repository's devcontainer (`devcontainer-rs`),
+3. lets the model explore the repository with read-only tools (`ls`, `read_file`,
+   `grep`, `find`) executed inside the container,
+4. posts the review and removes the container and the temporary clone.
+
+The container runtime is selected with `CONTAINER_RUNTIME` (`docker` or
+`podman`). The repository must contain a `.devcontainer/devcontainer.json`.
+
+Each sandbox is isolated: it gets its own image tag, container and network. The
+container starts with network access so the `postCreateCommand` /
+`postStartCommand` hooks can install dependencies (e.g. `npm install`); once the
+hooks have run, the container is disconnected from the network for the rest of
+the review. Every container command is bounded by a timeout, and the container,
+network and image are removed when the review ends (including on failure).
 
 ## Development