jayminwest/warren

Run coding agents like infrastructure, not terminal sessions. Warren manages isolation, lifecycle, spend, recovery, and Git delivery on compute you control.

Warren – Turning coding agents into managed workloads

What it is – Warren is an open‑source platform that lets you run coding‑agent processes (e.g., Claude Code, Pi) as first‑class, observable workloads on infrastructure you control. It handles the whole lifecycle: fresh isolated workspaces, execution monitoring, spend limits, live event streaming, automatic recovery, and finally committing the agent’s changes back to Git (optionally opening a pull request).

Why it matters – Large‑language‑model (LLM)‑based coding assistants are increasingly used to write, fix, or refactor code. Until now they are usually run from a developer’s terminal, which makes it hard to:

keep runs running unattended or on a schedule,
enforce resource or cost caps,
guarantee that the generated changes are safely persisted in version control,
observe and debug failures.

Warren provides the missing “infrastructure layer” so teams can treat an agent run like any other production job.

Core features (as described in the README)

Feature	What you get
Workspace isolation	Each run starts in a fresh worktree or clone on its own Git branch, sandboxed with `bwrap` (Linux) or `sandbox‑exec` (macOS).
Lifecycle management	Dispatch, monitor, cancel, finalize, and clean up runs automatically.
Live event stream	Real‑time JSON events are exposed via HTTP API, CLI, and UI, so you can watch progress or intervene.
Spend & concurrency limits	Define token‑usage or cost caps that are enforced while the agent runs.
Recovery	Watchdogs detect lost processes/pods and attempt graceful recovery; finalizers salvage work before teardown.
Git delivery	After a run finishes, Warren commits the changes, pushes the branch, and can open a PR via a GitHub App or static token.
History & observability	All run metadata (state, duration, cost, token usage, outcome) is stored and queryable through a unified HTTP API, CLI, and web UI.
Extensible runtimes	Supports three built‑in runtimes – `local` (bubblewrap/sandbox‑exec), `docker` (sibling container), and `k8s` (one pod per run). New runtimes can be added via adapters.
Extensions	Optional out‑of‑process packages (audit log, judging, campaign controller, Jira/Azure DevOps trackers) that plug into Warren’s HTTP surface.

How it works (high‑level flow)

Define a harness – a small program that talks to a coding model (e.g., Claude Code) and performs a task.
Deploy Warren – run curl … | sh && warren up on a macOS/Linux host, or use the provided Docker‑Compose / Kubernetes manifests.
Create a run – via the UI, CLI, or API you submit a repository + task description.
Warren spins up an isolated workspace on the selected runtime, launches the harness, and streams events.
During execution you can watch live logs, steer the run, or cancel it; spend limits are enforced.
On success the harness’s changes are committed, a branch is pushed, and (optionally) a PR is opened.
All metadata is persisted for later audit, cost analysis, or replay.

Getting started (quick‑start steps from the README)

# 1. Install the CLI (adds Bun and the `warren` binary)
curl -fsSL https://warren.run/install | sh

# 2. Bootstrap a local server (detects the best runtime for you)
warren up

The command opens a browser, walks you through GitHub connection, repository selection, and dispatches a starter run.

For a more production‑ready deployment you can clone the repo and launch the shipped Docker‑Compose stack:

git clone https://github.com/jayminwest/warren
cd warren
cp .env.example .env   # edit the secrets
docker compose up -d   # starts the server, DB, etc.

Then open http://localhost:8080, paste the minted operator token, add a repo, and start dispatching runs.

Who should use it

Individual developers or small trusted teams that already experiment with coding agents and want runs to survive beyond a terminal session.
Organizations that need to keep model credentials, compute, and generated code on‑prem (self‑hosted, no SaaS lock‑in).
Ops teams that want to enforce cost caps, observe run health, and automatically merge agent‑generated changes.

Documentation & resources

First‑run guide – docs/quickstart.md
Runtime & deployment guides – Docker (docs/self-host/docker.md), Kubernetes (docs/RUNBOOK-K8S.md)
API & SDK – OpenAPI spec (docs/openapi.yaml), TypeScript SDK (docs/sdk.md)
Extensions design – docs/design/extensions.md
Roadmap – ROADMAP.md
Live demo – https://app.warren.run (read‑only run history)
Discord community – linked badge in the README

Current status

Latest stable release: 0.19.1
Used in production on GKE, with unit, integration, and scenario tests covering the run lifecycle.
The core model is deliberately limited to a single shared‑token trust model (no per‑user RBAC yet).

License

MIT – free for personal, academic, or commercial use.